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Preface 


Controlling Document 


Audience 


Documentation Conventions 


This document describes SunCGI, an implementation of the ANSI Computer 
Graphics Interface (CGI) by Sun Microsystems, Inc. Previously, CGI was known 
as the Virtual Device Interface (VDI) standard. Appendix B summarizes the 
differences between SunCGI and ANSI CGI. 

The CGI standard is currently under development. Future releases of SunCGI 
will reflect changes in ANSI CGI. 

The following document was used in interpreting the CGI standard: 

[1] ANSI X3H3 84/85. Information Processing Computer Graphics Virtual 
Device Interface (VDI) Functional Description . March 1984. 

The intended reader of this document is an applications programmer who is fami¬ 
liar with interactive computer graphics and the C programming language. This 
manual contains several example programs that can be used as templates for 
larger SunCGI applications. 

Italic font is used to indicate file names, function arguments, variables and inter¬ 
nal states of SunCGI. Italics are also used in the conventional manner (to 
emphasize important words and phrases). ALL CAPS is used to indicate values in 
enumerated types. Bold font is used for the names of Sun software packages. 
Function names are printed with constant width font. 
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Introduction 


SunCGI provides access to low-level graphics device ftinctions without the res¬ 
trictions, benefits, or overhead of higher-level graphics packages like SunCore. 
SunCGI is usefiil for 2D graphics programs which do not require segmentation 
or transfonnations. The absence of segmentation from SunCGI makes drawing 
diagrams faster and simpler, but does not provide automatic picture regeneration. 
SunCGI programs are usually smaller and more efficient than SunCore pro¬ 
grams with similar functionality. In addition, SunCGI programs will mn on Sun 
devices without explicitly specifying the device at compile time. SunCGI pro¬ 
vides output primitives (for example, circles), attributes (for example, sophisti¬ 
cated pattern filling), and input primitives which are not offered by SunCore. 

The CGI standard is currently under development, and therefore, CGI has not been 
accepted by the X3H3 committee, ANSI, or ^e computer graphics community. 
Only certain models within CGI are supported by SunCGI. Specifically SunCGI 
implements input option sets 1,2,3,4, and 6 and output option sets 1 through 6 
of the CGI standard. CGI does not support 3D output primitives. 

SunCGI does provides output primitives, attribute selection, and input device 
management, at a level which is close to the actual device driver, thus affording 
speed and flexibility not offered by higher-level graphics packages like SunCore. 
SunCGI provides output primitives which are not provided by any of the other 
Sun graphics packages: for example disjoint polygons, circles, ellipses, and cell 
arrays (which can be thought of as scaled and transformed pixel arrays). CGI also 
provides a larger vocabulary of attributes than SunCore. SunCGI also provides 
facilities for explicitly binding virtual input devices to physical input devices as 
well as explicit management of an event queue . 

Here is a SunCGI example application program written in C: 


sun 
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- 

#include <cgidefs.h> 

Ccoor box[5] = { 10000,10000 , 

10000,20000 , 

20000,20000 , 

20000,10000 , 

10000,10000 ); 

mainO 

{ 

Ccoorlist boxlist; 

Cint name; 

Cvwsurf device; 

boxlist.n *= 5-; 
boxlist.ptlist = box; 

NORMAL_VWSURF(device, PIXWINDD); 

open_cgi () ; 

open_vws(finame, &device); 

polyline{&boxlist) ; 
sleep (10); 

close_vws(name); 
close_cgi(); 

} 


Figure 1-1 Simple Example Program 

SunCGI uses a variety of structures and enumerated types shown in Appendix C. 
The file <cgidef s. h> should be included in each SunCGI application pro¬ 
gram to provide necessary definitions and constants. 

Here is an example of a command line for compiling box. c to run in the Sun- 
View environment: 

- 

% cc box.c -o box -Icgi -Isunwindow -Ipixrect -Ira 
»_/ 


The order in which the libraries are linked to the program is important. 

All SunCGI functions can be called by one of two names: the expanded name 
(default) or the C language binding name. See Appendix H for information on 
the list of names for the shorter C language binding. 

As a final note, do not name any user-defined function or variable starting with 
the letters _cgi because doing so may disrupt the internal workings of SunCGI. 

FORTRAN programmers can access SunCGI functions by using the include file in 
cgidef s77 . h and using the /usr/lib/libcgi77 .a library to link with. 
Details of the FORTRAN interface to SunCGI are provided in Appendix G. 
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Q 1.2. The SunCGI Lint 
Library 


1.3. Overview of SunCGI 



SunCGI provides a lint library which provides type checking beyond the capa¬ 
bilities of the C compiler. For example, you could use the SunCGI lint library 
to check a program called glass . c with command like this: 



>» 

% lint glass.c -Icgi 



J 


Note that the error messages that lint generates are mostly warnings, and may 
not necessarily have any effect on the operation of the program. For a detailed 
explanation of lint, see the lint chapter in the Programming Tools manual. 

This section provides an overview of the substance of this manual. The four 
major sections of the manual (which correspond to chapters) are: 

1 ) view surface initialization and termination (control), 

2 ) output primitives, 

3) attributes, and 

4) input. 

The overview of these chapters contains a brief introduction to the basic concepts 
of CGI. The appendices at the end of this manual provide quick reference tables 
and descriptions of the interfaces between SunCGI and 

1) Sun View and 

2) FORTRAN. 


Initialization and Termination 



Chapter 2 describes functions for 

1 ) initializing and terminating the entire SunCGI package and individual view 
surfaces, 

2 ) defining the coordinate systems, 

3) interface negotiation, and 

4) signal trapping. 

The first section Chapter 2 describes functions for opening and closing view sur¬ 
faces (which are either windows or screens). SunCGI provides facilities for 
writing primitives to multiple view surfaces. Output primitives can be written to 
a selected subset of the open view surfaces by using the act ivate__vws and 
deactivate__vws functions (which turn a view surface on or off without clos¬ 
ing the view surface or affecting die display). The functions discussed in 
Chapter 2 also define the range of virtu^ device coordinates (VDC space) and 
device coordinates (screen space). The coordinates of most SunCGI functions 
are expressed in terms of VDC space. The limits of both VDC space and screen 
space can be defined by the application program. 

If you are attempting to run an application program developed on another 
vendor’s version of CGI, negotiation functions are provided which describe the 
capabilities of SunCGI. The application program can use the information 
obtained by using the negotiation functions to call appropriate functions in 


#sun 

Xr mJcrofyOems 


Version C jf 17 March 1986 





6 SunCGI Reference Manual 


Output Primitives 


Attributes 


Input 


Errors 


SunCGI to make the application program run correctly. Finally, Chapter 2 
describes SunCGI’s option for trapping SIGWINCH signals (generated by mani¬ 
pulating the window environment which the application program is using). 

SunCGI provides functions for drawing geometrical output primitives (for 
example, polygons, circles, and ellipses) as well as functions for performing ras¬ 
ter operations. The coordinates of output primitives are specified in vdc space 
(with the exception of some raster functions). Geometrical output primitives 
include rectangles, polymarkers, circular and elliptical arcs. Geometrical output 
primitives are affected by attributes described in Chapter 4 (like fill style and line 
width). All output primitives are affected by the drawing mode which deter¬ 
mines how an output primitives is affected by pixels which have been previously 
drawn on the screen. 

Attribute functions control the appearance of output primitives. Attributes can be 
set individually, or in groups which are called bundles. The use of most attri¬ 
butes is fairly straightforward; fill textures require a word of explanation. 
Geometrical output primitives can be filled with textures called hatches or pat¬ 
terns. Hatches are simply arrays of color values with each element of the array 
corresponding to a pixel. Patterns are arrays of color values which can be scaled 
and translated. 

SunCGI offers a standard interface for receiving input from the mouse and the 
keyboard. The CGI input model is based on the logical input device model in 
GKS. In this system, a logical input device (for example, a LCXIATOR device), 
is bound to a physical device (for example, die x-y position of the mouse) called 
a trigger. Triggers may be associated with logical input devices by the applica¬ 
tion program. Each logical input device has an associated measure (for example, 
the measure of a LOCATOR device is the mouse position on the screen). Each 
logical input device also has a state which determines how a device handles 
input. Each logical input device can be in one of five states: 

1) RELEASED (uninitialized), 

2) NO_EVENTS (initialized but unable to receive input), 

3) REQUEST_EVENT (waiting for one event), 

4) RESPOND_EVENT (report one event asynchronously), and 

5) QUEUE_EVENT (put each event at the end of the event queue ). 

Errors are reported in SunCGI by setting the return value of the function to a 
nonzero result and echoing an error message and number on the terminal. How¬ 
ever, error trapping can be controlled by the set_er ror_warning_inask 
function. An explanation of each error message (and suggestions for how to 
eliminate them) is presented in Appendix D. 
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Programming Tips 


Appendices 


1-4. References 


For novice C language users, the syntax of SunCGI may pose some initial 
difficulties. When a pointer is specified as an argument to a SunCGI function, 
SunCGI usually expects space to be allocated by the application program and 
the function argument to be preceded by an ampersand (&). SunCGI uses many 
enumerated types. These types are printed by the printf function as integers. 

If you want to print out these values in English, you should use the enumerated 
types as indices into a character array which contains appropriate English 
equivalents of the enumerated types. Finally, if you are a novice programmer, 
copy the example programs in Appendix E and use them as templates to build 
your own program with. Further help can be obtained by referring to the tables 
at the end of Appendix D, These tables list commonly encountered problems and 
how to solve them. 

The first five appendices are intended to make SunCGI easier to understand. 

This information will probably be particularly useful to novice users. The last 
two appendices describe the interfaces: 

1 . between SunCGI and Sun View, and 

2. between SunCGI and the FORTRAN programming language. 

Appendix A explains the difference between SunCGI and SunCore. Appendix 
B lists the ANSI CGI standard functions which are not implemented by SunCGI 
and the SunCGI functions which are not part of the ANSI CGI standard. Appen¬ 
dix C provides the type definitions used by the SunCGI functions. Appendix D 
lists the error messages and possible strategies for eliminating them. Appendix 
D also lists possible causes of simple run-time errors. Appendix E describes 
sample programs. 

The final two appendices describe the interfaces between SunCGI and other Sun 
software packages: SunView and FORTRAN. The first of the two interface appen¬ 
dices explains how to call SunCGI from application programs written on top of 
SunView. This interface allows SunCGI to write output primitives in different 
windows using different attributes. This interface is useful for application pro¬ 
grams which wish to control different areas of the view surface independently. 
Appendix G describes the interface to the FORTRAN programming language. The 
behavior of each SunCGI function is the same in both C and FORTRAN. 

[1] ANSI X3H3. Computer Graphics Virtual Device Interface. March 1984. 

[2] J.D. Foley and A. van Dam. Fundamentals of Interactive Computer 
Graphics. Addison-Wesley, 1982. 

[3] B.W. Kemighan and D.M. Ritchie. The C Programming Language. 
Prentice-Hall, 1978. 

[4] W.M. Newman and R.F. Sproull. Principles of Interactive Computer 
Graphics. McGraw-Hill, 1979. 

[5] V.R. Pratt. Staruiards and Performance Issues in the Workstation Market. 
IEEE Computer Graphics and Applications, April 1984. 
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[6] SunView Programmer's Guide. Sun Microsystems. 

[7] SunView System Programmer's Guide . Sun Microsystems. 

[8] Pixrect Reference Manual. Sun Microsystems. 

[9] SunCore Reference Manual . Sun Microsystems. 
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Initializing and Terminating SunCGI 


The current CGI standard does not provide functions for initializing and terminat¬ 
ing devices. ANSI CGI is intended to provide an interface for a single view sur¬ 
face (one per CGI instance), SunCGI extends CGI into the window environment 
by allowing a single CGI process to control multiple view surfaces. Six nonstan¬ 
dard functions open_cgi, close_cgi, open_vws, close__vws, 
activate_vws, and deactivate_vws are included in SunCGI. 
open_cgi and close_cgi initialize and terminate the operation of the 
SunCGI package. A view surface is initialized and terminated with open_vws 
and close_vws. A view surface is automatically activated when it is opened. 
SunCGI is capable of handling more than one view surface at once. Output pri- 
matives can be restricted from a view surface with deactivate_vws. 

A view surface is automatically activated when it is opened. However, a view 
surface can be deactivated (with the deactivate_vws function) when the out¬ 
put stream is not intended to appear on all view surfaces. Subsequent calls to 
SunCGI output functions will not apply to deactivated view surfaces^ until 
activate_vws is called again (see the following example). 


o 

^^2.1. View Surface 

Initialization and 
Selection 



^ However, inputs can be received on deacUvated view surfaces. 
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- ^ 

tinclude <cgidefs.h> 

main () 

{ 

Ccoor bot, top, center; 

Cint namel, name2, radius; 

Cvwsurf devicel, device2; 

bot.x “ 5000; 
bot.y = 5000; 
center.X = 10000; — 
center.y = 10000; 
radius = 5000; 
top.x = 15000; 
top.y = 15000; 

open_cgi(); 

NORMAL_VWSURF(devicel, PIXWINDD); 
open_vws(&namel, idevicel); 

NORMAL_VWSURF(device2, PIXWINDD); 
open_vws(&name2, &device2); 

rectangle(&bot, Stop); 
deactivate_vw3(name2); 
circle(ficenter, radius); 
activate_vws(name2) ; 
circle(scenter, 2*radius>; 

sleep(20); 

close_vws(namel); 
close_vws(name2); 
close_cgi(); 

} 

^; 



Figure 2-1 Example Program with Multiple Workstations 


Open CGI (SunCGI 
Extension) 


Errors 


Cerror open_cgi() 

open_cgi initializes the state of SunCGI to CGOP (CGi OPen). open_cgi 
does not initialize input devices but does initialize the event queue . No other CGI 
ftinctions can be used without generating an error if open_cgi has not been 
called. SunCGI traps various signals as described in Section 2.3. 

ENOTCGCL [1] CGI not in proper state: CGI shall be in state CGCL. 
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Table 2-1 SunCGI D^ault States 


State 

Value 

Range qfVDC space 

0-32767 in both x and y 
directions 

Clip Indicator 

CLIP 

Clip Rectangle 

Range of VDC space 

Error Warning Mask 

INTERRUPT 

Input Devices 

Uninitialized 

Input Queue 

EMPTY 

Trigger Associations 

Defaults specific values 
listed in Table 5-4 

Echo Modes 

Device specific values 
listed in Table 5-5 


You may be unfamiliar with some of the entries discussed in Table 2-1, How¬ 
ever, diese concepts are explained in the course of this chapter. Further, each of 
these concepts are referenced in the index. 

Open View Surface (SunCGI Cerror open_vws (name, devdd) 

Extension) Cint *name; /* name assigned to cgi view surface */ 

Cvwsurf *devdd; /* view surface descriptor */ 

open_vws initializes a view surface. The list of available view surfaces is 
described below in Table 2-2. open_vws initializes the attributes to their 
default values (listed in Table 2-3). The returned argument name is the identifier 
which is used to refer this view surface in other SunCGI functions. To reinitial¬ 
ize the state of the view surface without reopening it, use the hard_r eset 
function. 

More than one view surface can be open at one time. Output primitives arc 
displayed on all active view surfaces (view surfaces must be opened before they 
are activated). However, input is only echoed on the view surface which is 
pointed to by the mouse. Most of the Cvwsurf fields should be zeroed, as by 
the N0RMAL_VWSURF macro. Set the view surface type by assigning the dd 
(device driver) element of the devdd argument to the name of the appropriate 
device driver as in this example;^ 

Cvwsurf device; 

NORMAL_VWSURF(device, BW2DD); 
open_vws(&name, 4device>; 

Note : The NORMAL_VWSURF macro initializes the dd element of the Cvwsurf 
structure and guarantees that the view surface will be opened in the normal 
fashion. However, to open a window with some nonstandard parameters, or open 
a second window from a graphics tool read the following paragraphs. To use an 
existing pixwin , then skip the following paragraphs and read Appendix F instead. 


^ Noiice that when SunCGI specifies a pointer it usually requires that the argument is prefaced by an s 
character when the argument is actually used. 
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If the view surface of the specified type has been previously initialized and the 
type of view surface is a window (PDCWINDD or CGPIXWINDD), a CGI tool (a win¬ 
dow with the name CGI Tool) is opened. Other characteristics of the view surface 
can be defined by setting the other elements of the of the devdd argument (which 
is of type Cvwsurf). 

typedef struct { 

char screenname[DEVNAMESIZE]; /* physical screen */ 

char windowname[DEVNAMESIZE]; /* window */ 

int windowfd; /* window file descriptor */ 

int retained; /* retained flag */ 

int dd; /* device */ 

int cmapsize; /* color map size */ 

char cmapname[DEVNAMESIZE]; /* color map name */ 

int flags; /* new flag */ 

char **ptr; /* CGI tool descriptor */ 

) Cvwsurf; 

The elements screenname and windowname specify alternate screens (for exam¬ 
ple, /dev/cgoneO ) or alternate window (for example, IdevlwinlO). If these ele¬ 
ments are left blank, the current screen and the current window are used, unless 
the dd field implicitly specifies a device (for example CGIDD ). The element 
windowfd is the window file descriptor for the current device. The current 
implementation of SunCGI ignores this element. 

If the element retained is nonzero, fiien the view surface created by open_vws 
has a retained window associated with it (that is, if the window is covered up by 
another window and then revealed, the picture present before the window was 
covered-up will be redisplayed. By default the window created by open_vws is 
non-retained. That is, if the window is covered-up and then revealed the 
covered-portion will be redisplayed as white. However, drawing in non-retained 
windows is twice as fast as drawing in retained windows, so the choice of which 
type of view surface to open should be carefully considered. 

The dd element specifies the view surface type. The cmapsize and the cmap¬ 
name elements determine the size and the name of the colormap. No colormap 
is enabled for monochrome devices. The colormap determines the mapping 
between color indices and red, green, and blue values. If the colormap specified 
by the cmapname element of the devdd argument is the same as a colormap seg¬ 
ment which already exists, then the colormap segment is shared, cmapsize 
should be a power of two, less than or equal to 256. Refer to the SunView 
Programmer’s Guide for more information about colormaps. 

When the^gr element is nonzero, no attempt is made to take over the current 
graphics subwindow (if one exists). If this fiag is set or the graphics subwindow 
has already been taken over by SunCGI, then a CGI Tool (a window with the 
name View Surface Tool) is created. The ptr element specifies the size and 
placement of the CGI Tool, ptr is a pointer to an array of characters which 
should consist of nine decimal numbers separated by commas. The array takes 
the following form: 

*'nl, nt / nw, nh, il, it, iw, ih, I” 
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Errors 


Each element of the array should be filled with an integer. The first two elements 
specify the x and y coordinates of the upper left-hand comer of the CGI Tool. 

The third and fourth elements specify the width and height of the CGI Tool. The 
fifth through eighth elements specify the position and size of the iconic form of 
the CGI Tool. If the ninth element is nonzero, the tool is displayed in its iconic 
form. 


ENOTOPOP [5] 

ENOWSTYP [11] 
EMAXVSOP [12] 
EMEMSPAC [110] 
ENOTCCPW [112] 


CGI not in proper state CGI shall be either in state CGOP, 
VSOP, orVSAC. 

Specified view surface type does not exist 
Maximum number of view surfaces already open. 

Space allocation has failed. 

Function or argument not compatible with standard CGI. 


Table 2-2 Available View Surfaces 


Name 

Description 

PIXWINDD 

Sun View on a monochrome display 

CGPIXWINDD 

Sun View on a color display 

BWIDD 

Full screen on a Sun-1 mono¬ 
chrome display 

BW2DD 

Full screen on a Sun-2 or Sun-3 
monochrome display 

CGIDD 

Full screen on a Sun-1 color display 

CG2DD 

Full screen on a Sun-2 or Sun-3 
color display 

GPIDD 

Full screen on a Sun-2/160 or Sun- 
3/160 with optional Graphics Pro¬ 
cessor 


Table 2-3 View Surface D^ault States 


State 

Value 

View Surface 

Cleared 

Device Viewport 

View Surface 


Note : most failures during the opening of a view surface result in error ENOWS¬ 
TYP [11]. The most common reason is missetting (or failing to set) the dd ele¬ 
ment of the Cvwsurf structure. For example, opening a device surface type 
PIXWINDD instead of CGPIXWINDD on a color pixwin, or using CG2DD when 
the Idevicgtwo* surface is being used by suntools. The NORMAL_VWStJRF 
macro should be used to initialize this structure. 
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Activate View Surface Cerror activate_vws (name) 

{SunCGI Extension) Cint name; /* view surface name */ 

activate_vws activates the view surface specified by name. Subsequent 
SunCGI calls affect this view surface. Nothing is displayed on a view surface 
unless that view surface is active. Since a view surface is active as soon as it is 
opened, activate_vws is only need to reactivate a deactivated view surface. 
Note that activating a view surface may reset the state of SunCGI. 


Errors 

ENOTOPOP [5] 

CGI not in proper state CGI shall be either in state CGOP, 
VSOP.orVSAC. 


EVSIDINV [101 

Specified view surface name is invalid. 


EVSNOTOP [13] 

Specified view surface not open. 


EVSISACT [14] 

Specified view surface is active. 


Deactivate View Surface Cerror deactivate vws(name) 


(SunCGI Extension) 

Cint name; /* view surface name */ 

deactivate_vws prevents calls to SunCGI functions from having an effect 
on this view surface. The view surface may be reactivated by activate vws 
at a later time without having to be reopened. Note that deactivating a view sur¬ 
face may reset the state of SunCGI. 

Errors 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 

EVSIDINV [10] Specified view surface name is invalid. 

EVSNOTOP [13] Specified view surface not open. 

EVSNTACT [15] Specified view surface is not active. 

Close View Surface (SunCGI 

Cerror close_vws(name) 

Extension) 

Cint name; /* view surface name */ 

close_vws terminates a view surface. Future SunCGI calls have no effect on 
this view surface. The view surface cannot be reactivated without being reo¬ 
pened. 

Errors 

ENOTOPOP [5] CGI not in proper state CGI shall be either in state CGOP, 

VSOP.orVSAC. 

EVSIDINV [10] Specified view surface name is invalid. 

EVSNOTOP [13] Specified view surface not open. 

ENOTCCPW [112] Function or argument not compatible with standard CGI. 


Close CGI (SunCGI 
Extension) 


Cerror close_cgi() 

close_cgi terminates all open view surfaces, and restores the state of the Sun- 
View to the state that it was in before SunCGI was opened. Future SunCGI 
calls will have no effect and will generate errors. 
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A call to close__cgi should be included in the exit routines of an application 
program to guarantee leaving the SunView and SunCGI in a stable state. 

Errors ENOTOPOP [5] CGI not in proper state CGI shall be either in state CGOP, 

VSOP, orVSAC. 

ENOTCCPW [112] Function or argument not compatible with standard CGI. 

2.2. View Surface Control The functions described in this section 

1. define the range of world and device coordinates, 

2. control clipping, and 

3. reset selected aspects of the view surface and the internal state of SunCGI. 

Most functions in SunCGI express coordinates in VDC space (Virtual Device 
Coordinate space). In conventional computer graphics terms, VDC space 
corresponds to world coordinate space. The mapping between VDC space and 
screen space is determined by the physical size of the screen in pixels. Screen 
space is set by default to the entire size of the screen or the graphics window 
depending on the device type. The mapping from VDC space to screen space is 
always isotropic (the shape of the rectangle defining screen space is the same 
shape as vdc space). Therefore, VDC space defines the shape of the active view 
surface. The portion of screen space which does not correspond to VDC space is 
ignored. The aspect ratio (the ratio between the height and width) is therefore, 
defined by VDC space and not screen space. 

VDC Extent Cerror vdc_extent (cl, c2) 

Ccoor *cl, *c2; /* bottom left-hand and */ 

/* top right-hand corner of VDC space */ 

vdc_extent defines the limits of VDC space. The range of the coordinates 
must be between -32767 and 32767 (or an error is generated). VDC space can be 
set by the application program, but it ranges from 0 to 32767 in both the x and 
the y directions by default. Resetting VDC space impacts the display of output 
primitives on all view surfaces. 

Resetting the limits of VDC space automatically redefines the clipping rectangle 
to the new limits of VDC space, regardless of the value of the clip indicator . 

Changing the mapping from screen space to VDC space allows for translation 
(move) or scaling (zoom in/zoom out) of output primitives. However, no rota¬ 
tion functions are provided by SunCGI, and therefore, must be supplied in the 
application program. The code fragment below translates and zooms in on a rec¬ 
tangle; 
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- ^ 

#include <cgidefs.h> 

main 0 

Cvwsurf device; 

Cint name; 

Ccoor dvl, dv2, lower, upper; 

NORMAL_VWSURF(device, PIXWINDD); 

dvl.x = 0; 

dvl. y = 0; 

dv2 .X = 200; 

dv2.y = 2 0 0; 

lower.X = 30; /* rectangle coordinates */ 

lower.y = 30; 
upper.X = 70; 
upper,y = 70; 

open_cgi(); 

open_vws(&name, Sdevice); 
vdc_extent(&dvl, &dv2); 

rectangle(Supper, Slower); /* draw initial rectangle */ 

sleep(4); 

dvl.x =s 0; 

dvl.y = 0; 

dv2.X = 100; 

dv2.y = 100; 

vdc_extent(Sdvl, Sdv2); /* center rectangle */ 

rectangle(Supper, Slower); 

sleep(4); 

dvl .X = 20; 

dvl.y = 20; 

dv2 .X = 80; 

dv2.y = 80; 

vdc_extent(Sdvl, Sdv2); /* enlarge rectangle */ 
rectangle(Supper, slower); 
sleep(20); 

close_vws (ncime) ; 
close_cgi 0 ; 

} 

y_^ 


Errors 


Figure 2-2 Example Program with Multiple Normalization Tran^ormations 

ENOTOPOP [5] CGI not in proper state CGI shall be either in state CGOP, 
VSOP,orVSAC. 

EBADRCTD [20] Rectangle definition is invalid. 
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EVDCSDIL [24] VDC Space definition is illegal. 

ENOTCCPW [112] Function or argument not compatible with standard CGI. 


Device Viewport 


Errors 


Clip Indicator 


Cerror device_viewport(name, cl, c2) 

Cint name; /* name assigned to cgi view surface */ 

Ccoor *cl, *c2; /* bottom left-hand and top right-hand */ 

/* corner of view surface to map device onto */ 

/* (expressed in pixels) */ • 

device_viewport redefines the limits of screen space. If the new limits are 
not less fiian or equal to the size of the current screen or window size, an error is 
returned. Although device_viewport does not redefine the aspect ratio, it 
may redefine which areas of the screen are unused. 


ENOTOPOP [5] 

CGI not in proper state CGI shall be either in state CGOP, 
VSOP, orVSAC. 

EVSIDINV [10] 

Specified view surface name is invalid. 

EVSNOTOP [13] 

Specified view surface not open. 

EBADRCTD [20] 

Rectangle definition is invalid. 

EBDVIEWP [21] 

Viewport is not within Device Coordinates. 

ENOTCCPW [112] 

Function or argument not compatible with standard CGI. 


Cerror clip_indicator(cflag) 

Cclip cflag; /* CLIP, NOCLIP or CLIP_RECTANGLE */ 

For some application programs, it is desirable to clip explicitly within the 
viewport, while other applications may seek to increase efficiency by not check¬ 
ing if the coordinates are within the bounds of the clipping area. 

All SunCGI application programs will mn faster if clipping is turned off. How¬ 
ever, clipping is turned on by default to prevent SunCGI from drawing outside 
of the bounds of the window. 

The extent of vdc may be set with the vdc_extent function. 

The value of the argument cflag determines whether output primitives are 
clipped before they are displayed. The default state is CLIP. The advantage of 
mming clipping off is that it improves the speed of drawing primitives. How¬ 
ever, if clipping is set to NCXTLIP, SunCGI may draw output primitives outside of 
the window or within the bounds of an overiapping window. If clipping is not 
NOCLIP, output primitives are clipped to either die clip rectangle (if cflag equals 
CLIP_RECTANGLE), or the full extent of VDC space (if cflag equals CUP). 

typedef enum { 

CLIP, 

NOCLIP, 

CLIP_RECTANGLE 
} Cclip; 



Version C of 17 March 1986 





20 SunCGI Reference Manual 


Errors 


Clip Rectangle 


Errors 


Hard Reset 


Errors 


Reset to Defaults 


Errors 


ENOTOPOP [5] 
ENOTCCPW [1121 


CGI not in proper state CGI shall be either in state CGOP, 
VSOP, or vs AC. 

Function or argument not compatible with standard CGI. 


Cerror clip_rectangle (xmin, xmax, ymin., ymax) 

Cint xmin, xmax, ymin, ymax; /* bottom left-hand */ 

/* and top right-hand corner of clipping rectangle */ 

clip_rectangle defines the clipping rectangle in VDC Cooidinates. By 
default, the clipping rectangle is set to the borders of VDC space. The 
clip_rectangle function defines the clipping rectangle in VDC space, to be 
used when clipping is set to CLIP_RECTANGLE. The clipping rectangle is 
automatically reset by vdc_extent. 


ENOTOPOP [5] 

CGI not in proper state CGI shall be either in state CGOP, 
VSOP, or VSAC. 

EBADRCTD [20] 

Rectangle definition is invalid. 

ECLIPTOL [22] 

Clipping rectangle is too large. 

ECLIPTOS [23] 

Clipping rectangle is too small. 

ENOTCCPW [112] 

Function or argument not compatible with standard CGI. 


Cerror hard_reset() 

Device control functions restore the view surface and the internal state of 
SunCGI to a known state. The individual aspects of the device which can be 
reset are the output attributes, the view surface (screen), and the error reporting. 

hard_reset returns the output attributes to their default values; terminates all 
input devices, and empties the event queue and clears all view surfaces. VDC 
space is reset to its default values and the clip indicator is set to CLIP. This func¬ 
tion should be used sparingly because most control, attribute, and input functions 
called before this function will not have any effect on functions called after 
hard_reset is called. 

ENOTOPOP [5] CGI not in proper state CGI shall be either in state CGOP, ■ 
VSOP, or VSAC. 

Cerror reset_to_defaults() 

reset_to_def aults returns output attributes to defaults (see Table 4-1). 
reset_to_def aults does not clear the screen, reset the input devices, or 
reset the character set index. 

ENOTOPOP [5] CGI not in proper state CGI shall be either in state CGOP, 
VSOP. or VSAC. 

EVSIDINV [101 Specified view surface name is invalid. 
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Clear View Surface 


Errors 


Clear Control 


Errors 


Set Error Warning Mask 


Cerror cl€ar_view_surface<name, defflag, index) 

Cint name; /* name assigned to cgi view surface */ 

Cflag defflag; /* default color flag */ 

Cint index; /* color of cleared screen */ 

clear_view_sur f ace changes all pixels in the relevant area of the view sur¬ 
face specified by name to the color specified by the index argument, unless the 
defflag argument is set to OFF. If defflag is equal to OFF, the view surface is 
cleared to color zero. The area of the view surface which is actually cleared is 
determined by the clear_control function. clear_view_surf ace also 
resets the internal state of SunCGI according to previous calls to the 
clear_control function. clear_view_s-arf ace resets the current back¬ 
ground color to the color of the cleared view surface. 


ENOTVSAC [4] 

CGI not in proper state: CGI shall be in state VS AC 

EVSIDINV [10] 

Specified view surface name is invalid. 

EVSNOTOP [13] 

Specified view surface not open. 

EVSNTACT [15] 

Specified view surface is not active. 

ECINDXLZ [35] 

Color index is less than zero. 

EBADCOLX [36] 

Color index is invalid. 


Cerror clear_control(soft, hard, intern, extent) 

Cacttype soft, hard; /* soft and hard copy actions */ 
Cacttype intern; /* internal action */ 

Cexttype extent; /* clear extent */ 

clear_control determines the action taken when clear_view_surf ace 
is called. The argument soft can be set to either NO_OP or CLEAR. The argument 
hard which regulates clearing mles for plotters is ignored (because SunCGI 
does not currently support hard-copy devices) and is included only for ANSI CGI 
compatibility. The argument intern is set to either RETAIN or CLEAR. This 
parameter was included to support segmentation storage which is not currently a 
part of ANSI CGI. Therefore, the intern argument is ignored. The argument 
extent determines what area of the screen is cleared. It is set to one of the values 
in the Cexttype enumerated type: 

typedef enum { 

CLIP_RECT, 

VIEWPORT, 

VIEWSURFACE 
} Cexttype; 

ENOTOPOP [5] CGI not in proper state CGI shall be either in state CGOP, 
VSOP, orVSAC, 

ENOTCCPW [112] Function not compatible with CGIPW mode. 
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Cerror set_error_warning_inask (action) 

Cerrtype action; /* Action on receipt of an error */ 

set_error_warning_mask^ determines the action taken by SunCGI when 
an error occurs. Three types of action are possible; NO_ACnON, POLL, INTER¬ 
RUPT. If the action argument is set to NO_ACnON, errors are detected internally, 
but not reported. The error number is returned to the caller of a CGI routine. The 
user is advised not to set the action argument to NO_ACT10N. 

POLL and INTERRUPT actions print an error message on the terminal, but also 
return the error number (see Appendix D) so the program can perform exception 
handling. The default error_warning_inask is INTERRUPT. 

Errors ENOTOPOP [5] CGI not in proper state CGI shall be either in state CGOP, 

VSOP, or VSAC. 

Table 2-4 Error Warning Masks 


Error 

Warning Mask 

Message 

Printed 

Program 

Aborted 

Error 

Number Returned 

NO ACTION 

No 

No 

Yes 

POLL 

Yes 

No 

Yes 

INTERRUPT 

Yes 

FATAL errorst 

Non-FATAL errors 


t SunCGI defines no errors as FATAL. All errors are non-fatal so the appli¬ 
cation has complete control to abort or perform other processing as desired. 
Therefore, POLL and INTERRUPT are the same in SunCGI. 

2.3. Running SunCGI with SunCGI always traps five signals: SIGINT, SIGCHLD, SIGiO, SIGHUP and 

SunView SIGWINCH. The first four of these cause SunCGI cleanup and program termina¬ 

tion. When using a Graphics Processor option, SunCGI also traps SIGXCPU. 
Previous signal handlers, if any, are saved. When one of these signals occurs, 
SunCGI’s signal handler will call the previous signal handler as well as perform¬ 
ing its own processing. The actions of the previous (user installed) signal handler 
may interfere with SunCGI’s signal responses, and are hence unsupported. 

Unless a SunCGI application program has opened a retained view surface, over¬ 
lapping another window onto a graphics subwindow will destroy the picture 
below. SunCGI programs can regenerate a display surface by trapping the 
SIGWINCH (SIGn^ WINdow CHange) signal. 

It is possible (though unsupported) to install a signal handler for signals after cal¬ 
ling open__pw_cgi (see Appendix F). Since these signal handlers replace 
SunCGI’s handler, the application should save SunCGI’s signal handler 
(returned by signal), and call the saved handler when the signal occurs (amid the 
user’s own processing). Because the response of the program to the signal then 
depends on the place in the user’s own signal handling that SunCGI’s handler is 

^ The syntax of set_error_warnirg_mask in SunCGI is slightly different from the proposed ansi 
standard in that the ansi definition allows different actions for different classes of errors. 
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called, results are unpredictable, and may change with a new version of Sun CGI. 

Note that it is not necessary for an application to catch a SIGWINCH signal, since 
SunCGI’s set_up_sigwinch routine offers an easier interface. A user’s 
sig_f unction has a different calling semantics from a SIGWINCH in that 
pw_damaged and pw_donedainaged have already been invoked. 

When a window’s contents needs regeneration during execution time, the process 
associated with a window receives a SIGWINCH signal. The application can use 
this signal to determine when a view surface needs to be regenerated. Note ; 
Under no circumstances will the user be able to access the SIGWINCH signals gen¬ 
erated when a view surface is initialized. 

When a window obstructs a SunCGI view surface, output to that view surface is 
normally clipped to the exposed portion only (unless the clip indicator is 
NOCUP). When the obstraction is removed, unless the window is RETAINED, the 
picture must be regenerated by re-running the output generation of the applica¬ 
tions, for that view surface at least An application’s SIGWINCH handling func¬ 
tion is called for this purpose. 

When a SunCGI window’s size changes during execution, the picture must be 
regenerated. But first, SunCGI updates the transformation used to map VDC 
space into screen space. Then, if the affected view surface is RETAINED, the 
retained copy is rewritten onto the view surface. (Because of the size change, 
this may not repair the damage satisfactorily.) Lastly, the application’s 
SIGWINCH function is called. 

Set Up SIGWTNCH (SunCGI Cerror set_up_sigwinch (name, sig_function) 

Extension) Cint name; 

Cint (*sig_function) 0; /* signal handling function */ 

set_up_sigwinch allows the application program to trap SIGWINCH signals 
for view surface name. sig_f unction is a pointer to a fiinction returning an 
integer. If sig_function is nonzero, all SIGWINCH signals which are not 
trapped by the internals of SunCGI (from view surface initialization) are passed 
to the function specified by sig_function. 

The sig_f unction is called when the SIGWINCH signal is received. It is the 
programmer’s responsibility to use a flag to determine if it is safe to process the 
signal at this time, or to set a flag indicating that signal processing has been put 
off until later. See the SunView Programmer’s Guide for information on 
SIGWINCH handling. 

The sig_f unction argument is called with a single argument: the name of 
the view surface with which it is associated by the call to set_up_sigwinch. 
This allows more than one view surface to share the same sig__f unction, and 
differentiate which view surface needs redisplay. 

Here is an example of a program that uses set_up_s igwinch. 
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- ■■■■'■ -v 

#include <cgidefs.h> 

Ccoor box[5] = { 10000,10000 , 

10000,20000 , 

20000,20000 , 

20000,10000 , 

10000,10000 }; 

Cint name; 

extern Cint redraw(); 

Cvwsurf device; 

main () 

{ 

Ccoorlist boxlist; 

boxlist.n = 5; 
boxlist.ptlist = box; 

NORMAL_VWSURF(device, PIXWINDD); 

open_cgi () ; 

open_vws(&name, sdevice); 
set_up_sigwinch(name, redraw); 

polyline(&boxlist); 
sleep(10); 

close_vws(name); 
close_cgi(); 

} 

Cint redraw 0 
{ 

clear_view_surface(name, ON, 0); 

} 

V - — ^ 



Errors 


Figure 2-3 Example Program with set_up_sigwinch FM/icrion 

ENOTOPOP [5] CGI not in proper state CGI shall be either in state CGOP, 
VSOP,orVSAC. 


2.4. Interface Negotiation 


CGI is intended to support a ‘negotiated device interface’ which permits programs 
written on a specific type of hardware to run on other machines. SunCGI only 
allows inquiry of most of the settable modes.'^ For example the user may want to 
find out which types of input devices are supported. However, ftmctions for set¬ 
ting color precision, coordinate type, specification mode, and color specification 
are not provided because SunCGI only supports one type of color precision (8- 


* The functions which are not supported by SunCGI are classified as non-required by the March 1984 ansi 
cot standard. See Appendix B. 
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bit), coordinate type (integers), and color specification (indexed). The width and 
size specification modes are settable, but the fiinctions which set them are 
described in Chapter 4. However, the inquiry negotiation functions are supported 
so that an application program written for a CGI on another manufacturers’ 
workstation can find out whether the SunCGI is capable of running that applica¬ 
tion. 

Inquire Device Identification Cerror inquire_device_identification (name, devid) 

Cint name; /* device name */ 

Cchar devid[DEVNAMESIZE]; /* workstation type */ 

inquire_device_identif ication reports which type of Sun Worksta¬ 
tion view surface name is associated with. The argument devid may be set to 
one of the Sun Workstation types described in Table 2-2. The inclusion of the 
name argument deviates from the ANSI standard, but is necessary so that the 
characteristics of individual view surfaces may be inquired. 

ENOTOPOP [5] CGI not in proper state CGI shall be either in state CGOP, 
VSOP, or VSAC. 

EVSIDINV [10] Specified view surface name is invalid. 

EVSNOTOP [13] Specified view surface not open. 

Cerror inquire_device_class(output, input) 

Cint *output, *input; /* output and input abilities */ 

inquire_device_class describes the capabilities of Sun Workstations in 
terms of the CGI functions they support.^ Each of the two returned values repons 
the number of functions of each of the two classes which arc supported in 
SunCGI. These numbers (the values of input and output) are used to make 
more detailed inquiries by using functions 
inquire_input_capabilities and 
inquire_output_capabilities. 

ENOTOPOP [5] CGI not in proper state CGI shall be either in state CGOP, 
VSOP, or VSAC. 

Inquire Physical Coordinate Cerror inquire_physical_coordinate_system(name, xbase. 

System ybaae, xext, yext, xunits, yunits) 

Cint name; /* name assigned to cgi view surface */ 

Cint *xbase, *ybase; /* base coordinates */ 

Cint *xext, *yext; /* pixels in x and y directions */ 

Cfloat *xunits, *yunitS7 /* number of pixels per mm. */ 

inquire_physical_coordinate_system reports the physical dimen¬ 
sions of the coordinate system of view surface name in pixels and millimeters. 
inquire_jphysical_coordinate_system is provided to permit the 
drawing of objects of a known physical size. 

^ The output vgument does not include ihe Don-standard CGI functions. 


Inquire Device Class 


Errors 
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inquire_physical_coordinate_system is also provided to assist in 
the computation of parameters for the clevice_viewport function, xext and 
yext describe the maximum extent of the window in which the application pro¬ 
gram is run. (The window may or may not cover the entire screen.) The number 
of pixels per millimeter is always set to 0 because the actual screen size of device 
varies between individual monitors. The actual size of the screen may be 
obtained from the number of pixels in the x and y directions from the monitor 
specihcations and perform the division in an application program. 

Errors ENOTOPOP [5] CGI not in proper state CGI shall be either in state CGOP, 

VSOP.orVSAC. 

EVSIDINV [10] Specified view surface name is invalid. 

EVSNOTOP [13] Specified view surface not open. 


Inquire Output Function Set Cerror inquire_output_function_set (level, support) 

Cint level; /* level of output */ 

Csuptype *support; /* amount of support */ 

inquire_output_function_set reports the extent to which each level of 
the output portion of the ANSI CGI standard is supported. 

typedef enum { 

NONE, 

REQUIRED_FUNCTIONS_ONLY, 

SOME_NON_REQUIRED_FUNCTIONS, 

ALL_NON_REQUIRED_FUNCTIONS 
} Csuptype; 

The standard requires that the level argument be an enumerated type; however, 
for reasons of simplicity only the level number is used by SunCGI. Levels 1-6 
are supported completely (that is, both required and non-required functions are 
implemented. Level 7 is not supported at all. Refer to the ANSI standard for the 
precise definition of each level. 

Errors ENOTOPOP [5] CGI not in proper state CGI shall be either in state CGOP, 

VSOP, or VSAC. 


Inquire VDC Type Cerror inquire_vdc_type (type) 

Cvdctype *type; /* type of VDC space */ 

inquire_vdc_type reports the type of coordinates used by SunCGI in the 
returned argument type . 

typedef enum { 

INTEGER, 

REAL, 

BOTH 

} Cvdctype; 

type is always set to INTEGER (32-bit). SunCore is a higher-level graphics sys¬ 
tem with coordinate space expressed in real numbers. 
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Errors ENOTOPOP [5] CGI not in proper state CGI shall be either in state CGOP, 

VSOP, or VSAC. 

Inquire Output Capabilities Cerror inquire_output_capabilities (first, num, list) 

Cint first; /* first element */ 

Cint num; /* number of elements in list to be returned */ 
Cchar *list[]; /* returned list */ 

inquire__output_capabilities lists the output functions in the returned 
argument list. The range of the and num arguments is determined by the 
returned argument from the inquire_device_class function. 

ETors ENOTOPOP [5] CGI not in proper state CGI shall be either in state CGOP, 

VSOP.orVSAC. 

EINQLTL [16] Inquiry arguments are longer than list. 


2.5. Input Capability Input devices have a separate class of negotiation functions. Input capability 

Inquiries inquiries report qualitative abilities as well as quantitative abilities of input dev¬ 

ices. The inquire_input_capabilities function reports which devices 
and overall features are supported by SunCGI. The remaining functions report 
the capabilities of individual devices or features. Input devices are virtual dev¬ 
ices which must be associated with physical triggers (such as mouse buttons). 
Initializing an input device defines the measure used by a device, for example 
initializing a LOCATOR device defines the measure as x~y coordinates. In addi¬ 
tion to being associated with a trigger, each device has selectable screen echoing 
capabilities. Association and echoing capabilities for each input device are 
reported by the functions described in this section. 

Inquire Input Capabilities Cerror inquire_input_capabilities (valid, table) 

Clogical *valid; /* device state */ 

Ccgidesctab *table; /* CGI input description table */ 

inq;uire_input_capabilities reports the total number of input devices 
of each class that are supported. The argument valid returns the value L TRUE if 
SunCGI is initialized, and L_FALSE otherwise. If valid is set to L_TRUE, the ele¬ 
ments of table are set to the quanti^ and quality of inputs supported. All Sun 
Workstations support input at the same level. 
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Errors 


Inquire LID Capabilities 


typedef struct { 

Cint numloc; 

Cint numval; 

Cint numstrk; 

Cint numchoice; 

Cint numstr; 

Cint numtrig; 

Csuptype event_queue; 

Csuptype asynch; 

Csuptype coord_map; 

Csuptype echo; 

Csuptype tracking; 

Csuptype prompt; 

Csuptype acknowledgement; 

Csuptype trigger_manipulation; 

) Ccgidesctab; 

Elements of type Cint report how many of each type device is supported, as 
well as how many types of triggers are supported. Elements of type Csuptype 
report how many of the ftinctions of each class are supported. All functions 
except the tracking functions are fully supported. 

ENOTOPOP [5] CGI not in proper state CGI shall be either in state CGOP, 
VSOP, or VSAC. 


Cerror inquire_lid_capabilities(devclass, devnum, 
valid, table) 

Cdevoff devclass; 

Cint devnum; /* device number */ 

Clogical *valid; /* device supported at all */ 

Cliddescript *table; /* table of descriptors */ 

inquire_input_device_capabilities describes the capabilities of a 
specific input device (hereafter, specified device). The input arguments devclass 
and devnum refer to a specific device type and number. The argument valid 
reports whether CGI is initialized. 

typedef struct i 

Clogical sample;' 

Cchangetype change; 

Cint numassoc; 

Cint *triga3soc; 

Cinputability prompt; 

Cinputability acknowledgement; 

Cechotypelst *echo; 

Cchar *classdep; 

Cstatelist state; 

} Cliddescript; 

The elements of table which are of type Clogical indicate whether an ability 
is present in the specified logical input device. The change element reports 
whether associations are changeable at all (all input devices except string are 
changeable). The numassoc and trigassoc elements of table report how many 
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and which triggers may be associated with the specified logical input device. 
The echo argument describes which echo types are supported, (see Chapter 5 for 
a list of echo types).^ The classdep argument provides class dependent informa¬ 
tion in character form (the type of information is given in Table 2-3). If more 
than one piece of class dependent information is returned, then the pieces of 
information are separated by commas. The state argument reports the initial 
state of the specified device. See the inquire_state_list function. 

Table 2-5 Class Dependent Information 


Device Class 

Information 

Possible Values 

IC_LOCATOR 

Coordinate Mapping 

Yes, No, Partial 


Native Range 

xmin, xmax. 



ymin, ymax 

IC VALUATOR 

Set Valuator Range 

yes/no 

IC_STROKE 

Time Increment Settable 

yes/no 


Minimum Distance 

yes/no 

IC CHOICE 

Range 

min/max 

IC_STRING 

None 

None 


Errors 


Inquire Trigger Capabilities 



ENOTOPOP [5] CGI not in proper state CGI shall be either in state CGOP, 
VSOP.orVSAC. 

Cerror inquire_trigger_capabilities(trigger, valid, tdis) 
Cint trigger; /* trigger number */ 

Clogical *valid; /* trigger supported at all */ 

Ctrigdis *tdis; /* trigger description table */ 

inquire_trigger_capabilit ies describes how a particular trigger can 
be associated. The argument valid reports whether the device supports input at 
all. 

typedef struct { 

Cchangetype change; 

Cassoclid *numassoc; 

Cint maxassoc; 

Cpromstate prompt; 

Cackstate acknowledgement; 

Cchar *name; 

Cchar ^description; 

} Ctrigdis; 

The change element of tdis reports whether the specified trigger can be associ¬ 
ated with a logical input device. The numassoc element of tdis gives supported 
LID associations for this (rigger. This consists of n, the number of LID classes 
which can be associated with the trigger, a pointer to an array of n entries telling 
which n device classes can be associated with the trigger, and how many of each 

* Note that inquire_lid_capabilities mtums an enumerated type wliensas track_on accepts 
integers. Therefore these values may be different. 
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device class is defined. The maxassoc field gives the number of LID’s which 
can be concurrently associated with this trigger. SunCGI does not support either 
prompt or acknowledgement for any input device. The name element is simply a 
character form of the trigger name (for example, LEFT MOUSE BUTTON). The 
description element is never filled and is included for standards compatibility. 

Errors ENOTOPOP [5] 

EINTRNEX [86] 


CGI not in proper state CGI shall be either in state CGOP, 
VSOP, orVSAC. 

Trigger does not exist. 
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3.1. Geometrical Output Primitives 

Polyline. 

Disjoint Polyline. 

Polymarker. 

Polygon. 

Partial Polygon. 

Rectangle. 

Circle... 

Circular Arc Center . 

Circular Arc Center Close. 

Circular Arc 3pt. 

Circular Arc 3pt Close. 

Ellipse. 

Elliptical Arc. 

Elliptical Arc Close. 

3.2. Raster Primitives. 

Text. 

VDMText. 

Append Text. 

Inquire Text Extent. 

Cell Array... 

Pixel Array. 
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Output 


SunCGI supports two classes of output primitives: geometrical output primitives 
and raster primitives. 

Geometrical Output Primitives 

include arcs, circles, polylines, and polygons. The position of geometrical 
output primitives are always specified in absolute VDC coordinates.^ 

Raster Primitives 

draw text and scaled and unsealed 2D arrays. The coordinate system for ras¬ 
ter primitives depends on the type of primitive. The drawing mode deter¬ 
mines how output primitives are drawn on top of other output primitives or 
the background. 

3.1. Geometrical Output 
Primitives 


Geometrical primitives (except polymarker) are considered either closed or 
not closed. Polymarker uses its own attributes (see Section 4.3). Non-closed 
figures (polylines, circular arcs, or elliptical arcs) are drawn with a style, width 
and color determined from line attributes (see Section 4.2). Closed figures 
(polygons, rectangles, circles, ellipses, and circular and elliptical closed arcs) use 
the solid object attributes (see Section 4.4). The geometrical information 
specifies the boundary of a closed figure. The interior of this boundary is filled 
using fill area attributes. The boundary may be surrounded with a line, drawn 
with perimeter attributes, not the line attributes. For example, a circle of radius 
1000 and a perimeter width of 100 VDC units has its perimeter between the circle 
of radius 1000 and a concentric circle of radius 1100 (not from 950 through 
1050). 

Most polygonal primitives polyline, (polymarker, polygon, and 
partial_polygon) take one argument of type Ccoorlist: 


Geometrical output primitives are divided into two classes: polygonal primitives 
and conical primitives. Geometrical output primitives are all 2D in keeping with 
the CGI standard. However, polygons with holes (via the partial_polygon 
function) are provided in order to support 3D graphics packages. 


SunCGI (unlike SunCore) maintains no concept of cunent position. 
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typedef struct { 

Cint x; 

Cint y; 

} Ccoor; 

typedef struct { 

Ccoor *ptlist; 

Cint n; 

} Ccoorlist; 

The element ptlist is really a pointer to an array of type Ccoor which contains 
the n coordinates of the points defining the primitive. The style, color, and other 
features of lines, mariners, and fill patterns used by geometrical output primitives 
are set by the attribute functions described in Chapter 4, 

The polygons generated by SunCGI may or may not be closed. SunCGI 
automatically assumes the polygon is closed for the purpose of filling. However, 
a polygon must be explicitly closed in order to get all of its edges drawn, so take 
care to generate explicitly closed polygons. The rectangle function impli¬ 
citly generates closed objects.* 

SunCGI has two classes of conical primitives: circular and elliptical. Each 
class has functions for drawing solid objects, arcs, and closed arcs. Drawing of 
conical primitives is regulated by the same attributes that regulate the drawing of 
polygons and polylines. 

Polyline Cerror polyline (polycoors) 

Ccoorlist *polycoors; /* list of points */ 

polyline draws lines between the points specified by the ptlist element of 
polycoors . polyline does not draw a line between the first and last element 
of the point list To generate a closed polyline, the last point on the list must 
have the same coordinates as the first point on the list. The style, color, and 
width of the lines are set by the polyline_bundle_index, line_type, 
line_color, line_width and line_width_specif ication_mode 
functions. If a line segment of a polyline has a length of zero, the line is not 
drawn. To draw a point, use the circle function. If you specify a polyline that 
has less than two points, an error is generated, Similariy, if the number of points 
specified is greater than the maximum number of points (MAXPTS) an error is 



generated. 


Errors 

ENOTVSAC [4] 

CGI not in proper state: CGI shall be in state VSAC. 


ENMPTSTL [60] 

Number of points is too large. 


EPLMTWPT [61] 

polylines must have at least two points. 


Disjoint Polyline 


* A closed portion of a closed figure boundary will not be drawn if it exceeds a clipping boundary. 
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Errors 


Polymarker 


Errors 


Polygon 


Errors 

o 


Cerror disjoint_polyline(polycoors) 

Ccoorlist *polycoors; /* list of points */ 

dis joint_polyline draws lines between pairs of elements in ptUst. The 

line attributes described in Section 4.2 determine the appearance of the 

dis joint_polyline function. If polycoors contains an odd number of 

points, the last point is ignored. As with polyline, if the number of points is 

less than two or greater than MAXPTS, an error is generated. 

dis joint_polyline is typically used to implement scan-line polygon filling 

algorithms. 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VS AC. 
ENMPTSTL [601 Number of points is too large. 

EP LMTWPT [61 ] polylines'must have at least two points. 

Cerror polymarker(polycoors) 

Ccoorlist *polycoors7 /* list of points */ 

polymarker draws a marker at each point. The type, color, and size of marker 
are set by the polymarker_bundle_index, marker_type, 
marker_color, marker_si 2 e, and 

marker_size_specif ication_mode functions. If the number of points 
specified is greater than the maximum number of points, an error is generated, 
polymarker is useful for making graphs such as scatter plots. 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 

ENMPTSTL [60] Number of points is too large. 

Cerror polygon(polycoors) 

Ccoorlist *polycoors; /* list of points */ 

polygon displays the polygon described by the points in polycoors . In addi¬ 
tion, any points added to the global polygon list by the partial_polygon 
function are also displayed. The polygon is filled between edges. Polygons are 
allowed to be self-intersecting. The visibility of individual edges can only be set 
by the partial__polygon function. The style and color used to fill the 
polygon are set by the solid object attribute functions described in Chapter 4. 

The characteristics of the edges are controlled by the perimeter attribute func¬ 
tions. The number of points in the polygon used to determine the error condition 
of too few or too many points is the total number of points on the global polygon 
list , not the number of points specified in polycoors . After the polygon is 
drawn, the global polygon list is emptied. 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 

ENMPTSTL [60] Number of points is too large. 

EPGMTHPT [62] Polygons must have at least three points. 
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Partial Polygon 


EGPLISFL [63] Global polygon list is full. 

Cerror partial_polygon(polycoors, cflag) 

Ccoorlist *polycoors; /* list of points */ 

Ccflag cflag; /* CLOSE previous polygon? */ 

partial_polygon adds elements to the global polygon list without display¬ 
ing the polygon. The partial_polygon function provides the capability of 
drawing multiple-boundary polygons, including polygons with holes. The draw¬ 
ing is actually performed when polygon is called, polygon will close the last 
boundary on the global polygoniist and add the coordinate list it is passed as the 
final polygon boundary before drawing. 

cflag controls whether the last polygon in the global polygon list is open or 
closed. If cflag is set to CLOSE, the last polygon on the global polygon list will 
be closed by drawing a visible perimeter edge between ^e last and the first 
points of the last polygon on the global polygon list . If the cflag is set to OPEN, 
the points in polycoors are appended to the last polygon on the global polygon 
list , but an invisible perimeter edge will be drawn between the last point 
currently on the global polygon list and the first point in the Ccoorlist. The 
visibility of polygon edges can be individually controlled by calling 
part ial_polygon with cflag set to OPEN for each invisible edge and with 
cflag set to CLOSE for each new boundary. The interpretation of c^g is slightly 
different than the pseudocode given in the CGI standard. Future versions of CGI 
may use a different syntax to offer the capabilities of multiple-boundary 
polygons and invisible edges. 

The CGI standard specifies that circle, rectangle, ellipse and 
close_ar c are primitives that may use the global polygon list for filling. 
SunCGI does not use the global polygon list in these functions, and therefore 
leaves it untouched. These SunCGI routines do not empty the global polygon 
list . 
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r 


linclude <cgidefs.h> 

main () 

{ 

Ccoor list {4]; 


Ccoorlist points; 
Cint name; 

Cvwsurf device; 


NORMAL_VWSURF < device , PIXWINDD) ; 

open_cgi<) ; 


open_vws(Sname, Sdevice); 

interior_style(SOLIDI, ON); 

list[0] .X = 10000; 
list[0].y = 10000; 
list[1] .X = 10000, 
list[1].y = 20000, 
list[2] .X = 20000, 
list[2].y = 20000, 
list[3] .X = 20000, 
list [3] .y = 10000, 


points.ptlist=list; 

points.n=4; 


partial_polygon(Spoints , CLOSE); 

list[0] .X = 12500 
list[0].y = 12500 
list[1] .X = 12500 
list[1].y - 17500 
list[2] .X = 17500 
list[2].y = 17500 
list [3] .X - 17500 
list [3] .y = 12500 


points .ptlist=*list; 

points.n=4; 
polygon(fipoints) ; 

sleep(10) ; 

close_vws(name) ; 
close cgi{); 

} 

^. 

/* cut a hole in it */ 

. . - 


Figure 3-1 Example Program with Polygons 

An error is detected if the number of points on the global polygon list exceeds 
MAXPTS. In this case, the polygon on the global polygon list is drawn, and the 
new information is not added. The same error handling applies to polygon. 


Errors 
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Rectangle 


Errors 


Circle 


Errors 


Circular Arc Center 


ENOTVSAC [4] 
ENMPTSTL [60] 
EPGMTHPT [62] 
EGPLISFL [63] 


CGI not in proper state; CGI shall be in state VSAC. 
Number of points is too large. 

Polygons must have at least three points. 

Global polygon list is full. 


Cerror rectangle(rbc, Itc) 

Ccoor *rbc, *ltc; /* corners defining rectangle */ 

rectangle displays a box with its lower right-hand comer at point rbc and its 
upper left-hand comer at point Itc . Calls to rectangle do not affect the glo¬ 
bal polygon list . The interior of the rectangle (the filled portion) is defined by 
rbc and Itc . The perimeter is drawn outside of this region. The appearance of 
the rectangle is determined by the fill area and perimeter attributes. A rectangle 
with one side coincident with a clipping boundary specifies an interior extending 
to the boundary. Hence, a portion of the perimeter is outside the clipping boun¬ 
dary and is not drawn. 

If the arguments to rectangle would result in a point or a line, the point or 
line is drawn. However, if the arguments to rectangle determine a point, the 
point is drawn with width zero, regardless of the current value of perimeter 
width . If the values of rbc and Itc are reversed, the points are automatically 
reversed and the rectangle is drawn normally. 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 

Cerror circle{clf rad) 

Ccoor *cl; /* center */ 

Cint rad; /* radius */ 

circle draws a circle of radius rad centered at cl . The argument rad is 
expressed in terms of VDC space. The color, form, and visibility of the interior 
and perimeter are controlled by the same solid object attributes which control the 
drawing of polygons and rectangles. 

The argument rad determines the size of the interior of the circle. Therefore, a 
circle with a thick perimeter may be larger than expected. If the radius is zero, a 
point is drawn, and no textured perimeter is drawn, even if the perimeter width is 
large. If the radius is negative, die absolute value of the radius is used. 

Textured circles may possibly contain an incorrect element at one point because 
the digital circumference may not be exactly divisible by the length of the texture 
element. 

ENOTVSAC [4] CGI uot in proper state: CGI shall be in state VSAC. 

Cerror circular_arc_center(cl, c2x, c2y, c3x, c3y, rad) 

Ccoor *cl; /* center */ 

Cint c2x, c2y, c3x, c3y; /* endpoints */ 

Cint rad; /* radius */ 
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circular_arc_center draws a circular arc between points c2x, c2y and 
c3x, c3y with circle of radius rad at center cl. Point c2x , c2y is the starting 
point and point c3x, c3y is the ending point. Circular arcs are drawn in a coun¬ 
terclockwise manner. This convention is used to determine the difference 
between the arc formed by the smaller angle determined by c2x , c2y, cl and 
c3x , c3y and the larger angle specified by these same points. Therefore switch¬ 
ing the values of c2x, c2y and c3x , c3y will produce arcs which total 360 
degrees. If rad is negative, the points 180 degrees opposite from c2x , c2y and 
c3x, c3y are used as the endpoints of the arc. 

If the rad is zero, a point is drawn at cl . If either c2x , c2y or c3x, c3y are not 
on the circumference of the circle determined by cl and rad, an error is gen¬ 
erated and the arc is not drawn. The attributes which determine the style, width, 
and color of the arc are the same functions which regulate the drawing of poly¬ 
lines . 

Errors ENOTVSAC [4] CGI not in proper state: CGI shall be in state VS AC. 

EARCPNCI [64] Arc points do not lie on circle. 


Circular Arc Center Close Cerror circular_arc_center_close (cl, c2x, 

c2y, c3x, c3y, rad, close) 

Ccoor *cl; /* center */ 

Cint c2x, c2y, c3x, c3y; /* endpoints */ 

Cint rad; /* radius */ 

Cclosetype close; /* PIE or CHORD */ 

cir cular_arc_center_close draws a closed arc centered at cl with 
radius rad and endpoints c2x, c2y and 3x,c3y . Arcs are closed with either the 
PIE or CHORD algorithm. The PIE algorithm draws a line from each of the end¬ 
points of the arc to the center point of the circle. SunCGI then fills this region as 
it would any other solid object. The CHORD algorithm draws a line connecting 
the endpoints of the arc and then fills this region using solid object attributes. 
circular_arc_center_close is useful for drawing pie charts (see fol¬ 
lowing example): 
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#include <cgidefs.h> 

raainO /* draws four quadrants in different colors */ 

( 

Ccoor cl; 

Cint name, radius; 

Cvwsurf device; 

cl.x = 16000; /* center */ 

cl.y = 16000; 

NORMAL_VWSURF(device, CGPIXWINDD); 
radius = 8000; /* radius */ 

open_cgi(>; 

open_vws(Sname, &device); 
interior_style(SOLIDI, OFF); 

fill_color(1); /* color of quadrant 1 */ 

circular_arc_center_close(&cl, 24000, 16000, 

16000, 24000, radius, PIE); 
fill_color(2); /* color of quadrant 2 */ 

circular_arc_center_close(&cl, 16000, 24000, 

8000, 16000, radius, PIE); 
fill_color(3); /* color of quadrant 3 */ 

circular_arc_center_close(&cl, 8000, 16000, 

16000, 8000, radius, PIE); 
fill_color(4); /* color of quadrant 4 */ 

circular_arc_center_close{&cl, 16000, 8000, 

24000, 16000, radius, PIE); 

sleep (10); 
close_vws(name); 
clo3e_cgi(); 

1 

I__J 


Errors 


Figure 3-2 Example Program with Four Circle Quadrants in Different Colors 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 
EARCPNCI [64] Arc points do not lie on circle. 


Circular Arc 3pt 


Cerror circular_arc_3pt (cl, c2, c3) 

Ccoor *cl, *c2, *c3; /* starting, 

intermediate and ending points */ 

circiilar_arc_3pt draws a circular arc starting at point cl and ending at 
point c3 which is guaranteed to pass through point c2. The line attributes func¬ 
tions described in Section 4.2 determine the appearance of the 
circular_arc_3pt function. If the circular arc is textured (for example, 
dotted) then the intermediate point may not be displayed. However, if the arc is 
solid, the intermediate point is always drawn. If the three points are colinear, a 
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line is drawn. If two of die three points are coincident, a line is drawn between 
the two distinct points. Finally, if all three points are coincident, a point is 
drawn. circular_arc_3pt is considerably slowerthan 
circular_arc_center, therefore, you are advised to 
circular_arc_center if both functions can meet your needs. 

Errors ENOTVS AC [4] CGI not in proper state: CGI shall be in state VS AC. 

Circular Arc 3pt Close Cerror circular_arc_3pt_close (cl, c2, c3, close) 

Ccoor *cl, *c2, *c3; /* starting, intermediate 
and ending points */ 

Cclosetype close; /* PIE or CHORD */ 

circular_arc_3pt_close draws a circular arc starting at point cl and 
ending at point c3 which is guaranteed to pass through point c2 . The solid 
object attributes described in Section 4.4 determine the appearance of the 
circular_arc_3pt_close function. As with circular_arc_3pt, 
circular_arc_3pt_close is considerably slowerthan 
circular_arc_center_close; therefore, you are advised to use 
cir cular_arc_center_close if both functions meet your needs. 

If the Ehree points are colinear, a line is drawn. If two of the three points are 
coincident, a line is drawn between the two distinct points. Finally, if all three 
points are coincident, a point is drawn. In none of these cases will any region be 
filled. 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 

Cerror ellipse (cl, majx, miny) 

Ccoor *cl; /* center */ 

Cint majx, miny; /* length of x and y axes */ 

ellipse draws an ellipse centered at point cl with major (x) and minor (y) axes 
of length majx and miny If either majx or miny are zero, a line is drawn. If 
both majx and miny are zero, a point is drawn. The attributes which control the 
drawing of ellipses are the solid object attributes described in Section 4.4. 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 

Elliptical Arc Cerror elliptical_arc (cl, sx, sy, ex, ey, majx, miny) 

Ccoor *cl;/* center */ 

Cint sx, sy; /* starting point of arc */ 

Cint ex, ey; /* ending point of arc */ 

Cint majx, miny; /* endpoints of major and minor axes */ 

elliptical_arc draws an elliptical arc centered at cl with major (x) and 
minor (y) axes of length majx and miny. sx,sy and ex, ey are the starting and 

^ Although the axes are called the major and minor axes by the sundard they are really the x and y axes. In 
fact, the X axis can either be the major or minor axis, depending on the relative length of the y axis. 
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Errors 


Elliptical Arc Close 


Errors 


3.2. Raster Primitives 


Text 


ending points of the arc. An error is generated (and the ellipse is not drawn) if 
the points (i'x, , and ex, cy) are not on the perimeter of the ellipse. Elliptical 

arcs are drawn in a counterclockwise manner. This convention is used to deter¬ 
mine the difference between the arc formed by the obtuse angle determined by 
c}.x,c}.y ,sx,sy, and ex, ey and the acute angle specified by these same points. 
Therefore switching the values of sx,sy and ex, ey will produce complementaiy 
arcs. 

If either ma/x ormmy are zero, a line is drawn. If both majx and miny are zero, 
a point is drawn. Polyline attributes are used to determine the appearance of 
elliptical arcs. - 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 
EARCPNEL [65] Arc points do not lie on ellipse. 

Cerror elliptical_arc_close(cl, sx, sy, ex, 
ey, majx, miny, close) 

Ccoor *cl;/* center */ 

Cint sx, sy; /* starting point of arc */ 

Cint ex, ey; /* ending point of arc */ 

Cint majx, miny; /* endpoints of major and minor axes */ 
Cclosetype close; /* PIE or CHORD */ 

elliptical_arc_close draws an elliptical arc specified by sy, ex, ey 
and majx , miny . The arc is closed with either the PIE or CHORD algorithm. The 
same restrictions on sx, sy, ex, and ey are applied to 
elliptical__arc__close as to elliptical_arc. However, 
elliptical_arc_close uses the fill area and perimeter attributes, whereas 
elliptical_arc uses the line attributes. 

If either majx or miny are zero, a line is drawn. If both majx and miny are zero, 
a point is drawn. In neither of these cases will any region be filled. 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 

EARCPNEL [65] Arc points do not lie on ellipse. 

Raster primitives include text, cell arrays, pixel arrays, and bitblts (bit block 
transfer), Bitblts are pixel anays (bitmaps) which can be drawn using the various 
drawing modes. The current drawing mode determines how bitblt primitives are 
affected by information which is already on the screen. Rasmr primitives differ 
from geometrical primitives because their dimensions are not necessarily 
expressed in vdc space. Therefore, you must be carefiil to consider whether 
position arguments are expressed in VDC space or screen coordinates. 

Cerror text(cl, tstring) 

Ccoor *cl; /* starting point of text (in VDC space) */ 

Cchar *tstring; /* text */ 

text displays the text contained in tstring at point cl (expressed in VDC space). 
The appearance of text is controlled by the text attributes described in Section 
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Errors 

VDM Text 


Errors 

Append Text 


Errors 

Inquire Text Extent 


4.8. Control characters are displayed as blanks, except in the SYMBOL font where 
they may be drawn as pictures of bugs. 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 
Cerror vdiii_text (cl, flag, tstring) 

Ccoor *cl; /* starting point of text (in VDC space) */ 
Ctextfinal flag; /* final text for alignment */ 

Cchar *tstring; /* text */ 

v<im_text displays the text contained in tstring at point cl (expressed in VDC 
space). The intended difference between text and vdm_text is that 
vdin_text allows control characters; however, SunCGI does not handle control 
characters so text drawn with vdm__text will appear identical to text drawn 
with the text ftinction. If the fiag argument is equal to FINAL, the previous text 
and the appended text are aligned separately. However, if the flag argument is 
equal to NOT_FINAL, the appended and previous text are aligned together. 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 

Cerror appenci_text (flagtstring) 

Ctextfinal flag; /* final text for alignment */ 

Cchar *tstring; /* text */ 

append_text displays the text contained in tstring after the end of the most 
recently written text. The type of text written depends on the same attributes 
which control the display of text The flag argument determines whether the 
appended text is aligned with the previous text if the alignment is CONTINUOUS. 
If the y?ag argument is equal to FINAL, then the previous text and the appended 
text are aligned separately. However, if the flag argument is equal to 
NOT_FINAL, the appended and previous text are aligned together. 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 

Cerror inq[uire_text_extent (tstring, nextchar, concat, 
lleft, uleft, uright) 

Cchar *tstring; /* text */ 

Cchar nextchar; /* next character (for kerning) */ 

Ccoor *concat; /* concatenation point */ 

Ccoor *lleft, *uleft, *uright; 

/* coordinates of text bounding box */ 

inquire_text_extent determines how large text tstring would be and 
where it would be placed if it were drawn using the current text attributes. The 
nextchar parameter is used to determine the point where text would stan if more 
text (starting with nextchar ) were appended to the text specified by tstring If 
nextchar equals "single space ’, the last point of the current character is used. 
The argument concat returns the coordinates of the point where appended text 

This is a method for accounting for proportional spacing. 
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would Start. The arguments Heft , uleft , and aright return three of the four 
comers of the bounding box of text contained in tstring. 

The bounding box is a parallelogram (a rectangle if the character up vector and 
the character base vector are orthogonal). The names of the parallelogram 
comers are correct if no rotation is applied to the text. For some character orien¬ 
tations, the implied relationships do not hold. For example, Heft may not be the 
lowest. The fourth comer may be easily calculated from the three returned: 

uright->x + lleft->x - uleft->x 
uright->y + lleft-'>y - uleft->y 

The concatenation point and text alignment parallelogram are returned in vdc 
space, but assume a text position of (0,0). If the text is to be drawn at a position 
(x, y) then (x, y) must be added to each point to yield the true locations. 

The values of Heft , uleft , and aright are defined by the bounding box of the 
character and therefore may not be at the exact pixel where the character ends or 
begins. 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 


Cell Array 


Errors 


Cerror cell_array(p, q, r, dx/ dy, colorind) 

Ccoor *p, *q, *r; 

/* corners of parallelogram (in VDC space) */ 

Cint dx, dy; /* dimensions of color array */ 

Cint *colorind; /* array of color values */ 

cell_array draws a scaled and skewed pixel array on the view surface(s). 
Points p, q and r (expressed in VDC space) define a parallelogram. Line p-q is a 
diagonal and p is the lower left-hand comer, r is one of the remaining two 
comers, dx and dy define the width and the height of the array colorind which 
is mapped onto the parallelogram defined hy p ,q, and r . 

cell_array is one of the few primitives which depends on the actual size of 
the view surface. Cell arrays are not drawn if the elements of the array would be 
smaller than one pixel. However, because different view surfaces may have dif¬ 
ferent dimensions, a cell array might be drawn on one view surface, but not on 
another smaller view surface. Finally, all cells composing the cell array are the 
same size; therefore, the upper left hand comer of the cell array might be down 
and to the right of point q because of the accumulated error of making all of the 
cells slightly smaller than their floating point size. For example if each cell of a 
3x3 cell array is supposed to be 3.333 pixels wide, the actui cell array will be 
nine pixels wide instead of ten. 

ENOTVSAC [4J CGI not in proper state: CGI shall be in state VSAC. 

ECELLATS [66] Cell array dimensions dx , dy are too small. 

ECELLPOS [67] Cell array dimensions must be positive. 


Pixel Array 
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Errors 


BilBlt Source Array 


Errors 


Cerror pixel_array(pcellf m, n, colorind) 

Ccoor *pcell; /* base of array in VDC space */ 

Cint III, n; /* dimensions of color array in screen space */ 
Cint *colorind; /* array of color values */ 

pixGl_array draws array colorind starting at point pcell (expressed in VDC 
space), m and n (expressed in screen space) define the x and y dimensions of 
the array. Therefore, pixel arrays always have a constant physical size, indepen¬ 
dent of the dimensions of VDC space. The pixel array is drawn down and to the 
right from point pcell . If either m or n are not positive, the absolute value of m 
and n are used. pixel_array is not affected by the current drawing mode. 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 
EVALOVWS [69] Value outside of view surface. 

Cerror bitblt_source_array(pixsource, xo/ yo, xe, ye, 
pixtarget, xt, yt, name) 

Cpixrect *pixsource, *pixtarget; 

/* source and target pixel arrays */ 

Cint xo, yo; 

/* coordinates of source array (in VDC*space) */ 

Cint xe, ye; 

/* dimensions of source array (in screen space) */ 

Cint xt, yt; 

/* coordinates of target pixel array (in VDC space) */ 
Cint name; /* view surface name */ 

bitblt_source_array moves a pixel array from point {xo,yo) to point 
(xt , yt ) using the current drawing mode . Both of these points are expressed in 
VDC space. The size of the pixel array is determined by the xe and ye arguments 
which are expressed in screen space, pixsource and pixtarget are pointers to pix- 
rects which must already be created by mem_create.^^ These pixrects must be 
the same depth as the view surface: 1-bit deep on a monochrome device, 8-bit on 
a color device. The source area of the view surface associated with name is 
saved into pixsource (at 0,0). The target area, after pixsource is applied 
to it, is read into pixtarget pixnect (at 0,0). 

An error is detected if either xe or ye are not positive. If the replicated pattern 
array overlaps with the source array on the screen, the visual result depends on 
the current drawing mode . pixsource and pixtarget may have different contents . 
depending on the screen drawing mode (see the set_drawing_mode func¬ 
tion). 

Multiple view surfaces and bitblt’s are incompatible, so a name argument must 
be specified. 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 


” Refer 10 the Pixrect Reference Manual for more infoinution about pixrects. 
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EVALOVWS 169] 


Value outside of view surface. 


BitBlt Pattern Array 


Errors 


Cerror bitblt__pattern_array (pixpat, px, py, pixtarget, 
rx, ry, ox, oy, dx, dy, name) 

Cpixrect *pixpat; /* pattern source array */ 

Cint px, py; /* pattern extent */ 

Cpixrect *pixtarget; /* destination pattern array */ 
Cint rx, ry; /* pattern reference point */ 

Cint ox, oy; /* destination origin */ 

Cint dx, dy; /* destination extent */ 

Cint name; /* view surface name */ 


bitblt_pattern_array replicates the pattern (using the current drawing 
mode ) stored in piiq>at to fill the area of the view surface which is determined by 
ox , oy and dx,^. The pattern reference point determines the offset of the pat¬ 
tern array from the point zero. The resultant pattern array is displayed at ox,oy. 
The visual result depends on the current drawing mode. 

pixpat is a pointer to a pixrect which must be created and initialized with the 
pattern by the application program, pixtarget is a pointer to a pixrect (with 
same depth as the device) which must already be created by the user, using 
mem_create. The target area, after pixpat is applied to it, is read into the 
pixtarget pixrect (at 0,0). 


Multiple view surfaces and bitblt’s are incompatible, so a name argument must 
be specified. 



ENOTVSAC [4] 
EVALOVWS [69] 
EPXNOTCR [70] 


CGI not in proper state: CGI shall be in state VS AC. 
Value outside of view surface. 

Pixrect not created. 


BitBlt Patterned Source Array Cerror bitblt_patterned_source_array (pixpat, px, py, 

pixtarget, rx, ry, pixsource, sx, sy, ox, oy, 
dx, dy, name) 

Cpixrect *pixpat; /* pattern source array */ 

Cint px, py; /* pattern extent */ 

Cpixrect *pixsource; /* source array */ 

Cint 3X, sy; /* source origin */ 

Cpixrect *pixtarget; /* destination pattern array */ 
Cint rx, ry; /* pattern reference point */ 

Cint ox, oy; /* destination origin */ 

Cint dx, dy; /* destination extent */ 

Cint name; /* view surface name */ 


bitblt_patterned_source_array replicates (using the current drawing 
mode) the pattern stored in pixpat to fill the area of the view surface deter¬ 
mined by ox, oy and dx, dy. The source area of the view surface is read into 
the pixrect pointed to by pixsource (which must already be created by the 
user with same depth as the device) at 0,0. The soiirce area is stenciled through 
the replicated pattern onto the view surface at ox, oy, using the current drawing 
mode. The target area, after the copy, is read into the pixtarget pixrect. If 
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o 


Errors 


Inquire Cell Array 


Q 


Errors 


Inquire Pixel Array 


o 


the replicated pattern array overlaps with the source array on the screen, the 
visual result depends on the current drawing mode. 

Multiple view surfaces and bitblt’s are incompatible, so a name argument must 
be specified. 

ENOTVSAC [4] CGI not in proper state; CGI shall be in state VSAC. 
EVALOVWS [69] Value outside of view surface. 

EPXNOTCR [70] Pixrect not created. 

Cerror inquire_cell_array<name/ p, q, r, dx, dy, colorind) 
Cint name; /* view surface name */ 

Ccoor *p, *q, *r; 

/* corners of parallelogram (in VDC space) */ 

Cint dx, dy; /* dimensions of color array */ 

Cint *colorind; /* array of color values */ 

Points p, q and r (in VDC space) define a parallelogram with line p-q as the 
diagonal where p is the lower left-hand comer, r is one of the remaining two 
comers, dx and dy define the width and the height of the array colorind which 
contains the colors of the pixels on the screen which lie within the parallelogram • 
defined hy p,q, and r. Notice that a view surface identifier, name , must be 
specified because the result of this function is highly dependent on the dimen¬ 
sions and contents qf the view surface. 

The area of the screen corresponding to the parallelogram is assumed to contain a 
regular grid of points. However, if each element of the grid is larger than one 
pixel, the color of the pixel at lower left-hand comer of each element of the grid 
is defined to be the color of the grid element. Therefore, the values contained in 
colorind are highly dependent on the size of the view surface. An error is pro¬ 
duced if the elements of die grid are smaller than one pixel. 


ENOTVSAC [4] 
EVSIDINV [10] 
EVSNOTOP [13] 
EVSNTACT [15] 
ECELLATS [66] 
ECELLPOS [67] 


CGI not in proper state; CGI shall be in state VSAC. 
Specified view surface name is invalid. 

Specified view surface not open. 

Specified view surface is not active. 

Cell array dimensions dx, dy are too small. 

Cell array dimensions must be positive. 


Cerror inq[uire_pixel_array(p, m, n, colorind, name) 

Ccoor *p; /* base of array in VDC space */ 

Cint m, n; /* dimensions of color array in screen space */ 
Cint *colorind; /* array of color values */ 

Cint name; /* view surface name */ 

inquire_pixel_array fills array colorind with the values of pixels in the 
area of the screen defined by point p (expressed in VDC space) and m and n 
(expressed in screen space). The array is filled dawn and to the right from point 
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p. If either m or n are not positive, the absolute value of these arguments is 
used. 

Multiple view surfaces and bitblt’s are incompatible, so a name argument must 
be specified. 

Errors ENOTVS AC [4] CGI not in proper state: CGI shall be in state VS AC. 

EVALOVWS [69] Value outside of view surface. 

EPXNOTCR [70] Pixrect not created. 

Inquire Device Bitmap Cpixrect *inquire_device_bitmap (name) 

Cint name; /* name assigned to cgi view surface */ 

inquire_device_bitmap remms the pixrect which corresponds to the view 
surface. The pixrect describes the entire device, even if the view surface is a 
smaller pixwin. If you want to use subareas of this pixrect or manipulate it any 
other way, refer to the Pixrect Reference Manual . 

Errors ENOTOPOP [5] CGI not in proper state CGI shall be in in state VDOP, 

VSOP,orVSAC. 

A ' 


Inquire BitBlt Alignments 


Errors 


3.3. Drawing Modes 


Cerror inquire_bitblt_alignments(base, width, px, py, 
maxpx, maxpy, name) 

Cint *base; /* bitmap base alignment */ 

Cint *width; /* width alignment */ 

Cint *px, *py; /* pattern extent alignment */ 

Cint *maxpx, *maxpy; /* maximum pattern size */ 

Cint name; /* name assigned to cgi view surface */ 

inquire_bitblt_alignments reports the alignment criteria which are 
necessary for some implementations. These factors are not critical for SunCGI, 
However, you should keep in mind the appropriate depth for the pixrect when 
talking to a specific device. Therefore the arguments base , width, px , and py 
are always set to zero. The arguments maxpx and maxpy are device dependent 
and determine the maximum size of a pattern forbitblt_pattern__array 
and bitblt_patterned_source_array. 

Multiple view surfaces and bitblt’s are incompatible, so a name argument must 
be specified. 


ENOTVSAC [4] 
EVSIDINV [10] 
EVSNOTOP [13] 
EVSNTACT [15] 


CGI not in proper state: CGI shall be in state VSAC. 
Specified view surface name is invalid. 

Specified view surface itot open. 

Specified view surface is not active. 


Drawing modes determine the result of drawing any output primitive on the clear 
screen (background) or on top of a previously drawn object. Drawing modes 
only affect the drawing of bitblt primitives. However, a non-standard 
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Set Drawing Mode 


Errors 


set_global_drawing_mode function is provided, which affects all output 
primitives except bitblt’s. Resetting the drawing mode in the middle of an appli¬ 
cation program only affects those output primitives drawn after the mode is reset. 
The novice user is advised not to reset the drawing mode until the user has writ¬ 
ten at least one application program using SunCGI, 

Cerror set_drawing_inode (visibility, source, 
destination, combination) 

Cbmode visibility; /* transparent or opaque */ 

Cbitmaptype source; /* NOT source bits */ 

Cbitmaptype destination; /* NOT destination bits */ 
Ccombtype combination; /* combination rules */ 

set_drawing_mode determines the current drawing mode which in turn 
determines how bitblt primitives are displayed. The visibility argument deter¬ 
mines how pixels with index zero are treated. 

typedef enum { 

TRANSPARENT, 

OPAQUE 
) Cbmode; 

typedef enum { 

BITTRUE, 

BITNOT 

} Cbitmaptype; 

typedef enum { 

REPLACE, 

AND, 

OR, 

NOT, 

XOR 

} Ccombtype; 

If visibility is set to TRANSPARENT, all source pixels with index zero leave the 
destination pixel unchanged, regardless of the operation, whereas if visibility is 
set to OPAQUE, all pixels are treated normally. The arguments source and desti¬ 
nation determine whether the contents of the source and destination pixrects are 
NOTted before the bitblt operation is performed. 

The combination argument determines how the source and destination pixrects 
are combined. If combination is equal to REPLACE, the source pixrect (after 
optionally being NOT-ted) replaces the destination pixrect. If combination is 
equal to AND, OR, or XOR the source pixrect and the destination pixrect are com¬ 
bined in the indicated Boolean fashion. If combination is equal to NOT, then the 
destination is set to a bitwise NOT operation of the source pixrect 

ENOTOPOP [5] CGI not in proper state CGI shall be in in state VDOP, 
VSOP, orVSAC. 
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Set Global Drawing Mode 
(SunCGI Extension) 


Errors 


Cerror set_global_drawing_rnode (combination) 

Ccombtype combination; /* combination rules */ 

set_global_drawing_mode determines the current global drawing mode 
which in turn determines how all output primitives except bitblts are displayed. 
The combination argument determines how the source and destination pixrects 
are combined. If combination is equal to REPLACE (the default value) the output 
primitive replaces the destination background. If combination is equal to AND, 
OR, or XOR the output primitive and the information on the screen are combined 
in the indicated Boolean fashion. If combination is equal to NOT, then the desti¬ 
nation is set to a bitwise NOT operation of the source pixrecL 

ENOTOPOP [5] CGI not in proper state CGI shall be in in state VDOP, 
VSOP, orVSAC. 


Inquire Drawing Mode Cerror inquire_drawing_mode (visibility, source, 

destination, combination) 

Cbmode *visibility; /* transparent or opaque */ 

Cbitmaptype *source; /* NOT source bits */ 

Cbitmaptype *destination; /* NOT destination bits */ 

Ccombtype *combination; /* combination rules */ 

♦ 

The inquire_drawing_mode returns the values of the four components of 
the current drawing mode. 

Effors ENOTOPOP [5] CGI not in proper state CGI shall be in in state VDOP, 

VSOP, or VSAC. 
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Attributes 


The current attributes determine how output primitives are displayed. Attributes 
are not specific to any view surface, but affect all view surfaces. The default 
attributes are defined in Table 4-1. The current attributes may be set either indi¬ 
vidually or in groups (by changing the index into the bundle table ). Example 
programs illustrating these methods of changing attributes are given in Figures 
4-1 and 4-2. 

Each entry in the bundle table specifies a set of attributes for a particular type of 
primitive (for example, solid objects). The method for setting the current attri¬ 
butes depends on the state of the ASF {aspect source fiag ) for each attribute. For 
individual attribute functions to have an effect, the ASF must be set to INDIVI¬ 
DUAL, If the ASF is set to BUNDLED, the current attribute is defined by the entiy 
in the bundle table pointed to by the bundle index. The actual appearance of 
objects also depend on the global drawing mode described in Chapter 3. 

The majority of this chapter is devoted to individual attribute functions. Indivi¬ 
dual attribute functions are grouped according to the output primitives they 
effect: polylines, polymarkers, filled objects, and text. The color_table 
function (which redefines color table entries) is also included in this chapter. 
Finally, functions for obtaining the values of the current attributes are discussed. 
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Table 4-1 D^ault Attributes 


Attribute 

Value 

Attribute 

Value 

All ASF’s 

individual 

All Bundle Indices 

1 

Line Color 

1 

Line Width 

0.0 

Line Endstyle 

BEST_FIT 

Line Width 

SCALED 

Line Type 

SOLID 

Specification Mode 


Marker Color 

1 

Marker Size 

4.0 

Marker Size 

SCALED 

- Marker Type 

DOT 

Specification Mode 




Fill Color 

1 

Number of Pattern 

2 

Fill Hatch Index 

0 

Table Entries 


Fill Pattern Index 

1 

Pattern Size 

300,300 

Interior Style 

HOLLOW 

Pattern Reference Point 

0,0 



Pattern with Fill Color 

OFF 

Perimeter Color 

1 

Perimeter Width 

SCALED 

Perimeter Type 

SOLID 

Specification Mode 


Perimeter Width 

0.0 

Perimeter Visibility 

ON 

Fontset 

1 

Text Font 

STICK 

Fixed Font 

0 



Character Basejc 

1.0 

Character Spacing 

0.1 1 

Character Base.y 

0.0 

Character Up-v 

0.0 1 

Character Expansion Factor 

1.0 

Character Up.y 

1.0 

Character Height 

1000 

Text Color 

1 

Character Path 

RIGHT 

Text Precision 

STRING 

Horizontal Text 

NRMAL 

Text Continuous 

1.0 

Alignment 


Alignment.y 


Text Continuous 

1.0 

Vertical Text 

NORMAL 

Alignment, a: 


Aligrunent 



4.1. Bundled Attribute The attribute environment selector functions determine if the current attributes 

Functions are defined individually or by using a set of attributes (bundles). Bundles are 

defined by entries in the bundle table. The CGI standard specifies the bundle 
table as read-only but SunCGI allows user-definition of entries in the bundle 
table. Each type of primitive has its own index into the btmdie table, described 
with its specific attribute functions. 

The following example program illustrates how to change the appearance with 
bundled attributes. The program draws a polyline with a different line style and 
line width. 
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-- 

#include <cgidefs.h> 

Ccoor box[5] = { 10000,10000 , 

10000,20000 , 

20000,20000 , 

20000,10000 , 

10000,10000 ); 

Cbunatt bundle = { DASHED_DOTTED, 1., 4, 

X, 6., 4, 

PATTERN, 1, 1, 2, 

DOTTED, 1.5, 1, 

STICK, CHARACTER, 

1.3, 0.05, 1 }; 

main() 

Ccoorlist boxlist; 

Cint i, lin€_bundle = 2, name; 

Cflaglist flags; 

Cvwsurf device; 

boxlist.ptlist = box; 
boxlist.n = 5; 

NORMAL_VWSURF(device, PIXWINDD); 
open_cgi(); 

open_vws(finame, fidevice); 

flags.value = (Casptype *) malloc(18*sizeof(Casptype)); 
flags,num = (Cint *) malloc{18*sizeof(Cint)); 
for (i = 0; i < 18; i++) { 

flags.value[i] = BUNDLED; 
flags.num[i] = i; 

} 

flags.n = 18; 

define_bundle_index(2, Sbundle); 
set_aspect_30urce_flags(&flags); 
polyline_bundle_index(line_bundle); 
polyline(iboxlist); 

sleep(10); 
close_vws(name); 
close_cgi(); 

} 

's_- 


Figure 4-1 Example Program with Bundled Attributes 


#sun 

^ meroeystfliT* 


Version C of 17 March 1986 






56 SunCGI Reference Manual 


Set Aspect Source Flags Cerror set_aspect_source_flags (flags) 

Cflaglist *flags; /* list of ASFs */ 

set_aspect_source_flags determines whether individual attributes are 
set individually or from bundle table entries. 

typedef struct { 

Cint n; 

Cint num[]; 

Casptype value [ ]; 

} Cflaglist; 

The « element of the flags argument determines how many flags are to be set. 
The num array of the flags argument determines which flags are to be set. 

Flag numbers are provided in Table 4-2. Finally, the value array of the flags 
argument determines the values of the flags specified in num . If a value is 
assigned to INDIVIDUAL, the individual attribute functions affect the current attri¬ 
bute. If the value of index is BUNDLED, calls to individual attribute functions 
have no effect}^ The default bundle index is set to 1 (which initially contains 
the default value for the attributes specified in Table 4-1). The default value of 
all aspect source flags is INDIVIDUAL. 

Errors ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 

VSOP.or VSAC. 

Table 4-2 Attribute Source Flag Numbers 


Flag 

Attribute 

Flag 

Attribute 

0 

line type 

9 

fill color 

1 

line width 

10 

perimeter type 

2 

line color 

11 

perimeter width 

3 

marker type 

12 

perimeter color 

4 

marker width 

13 

text font index 

5 

marker color 

14 

text precision 

6 

interior style 

15 

character expansion factor 

7 

hatch index 

16 

character spacing 

S 

pattern index 

17 

text color 


Define Bundle Index (SunCGI Cerror define_bundle_index (index, entry) 

Extension) Cint index; /* entry in attribute environment table */ 

Cbunatt *entry; /* new attribute values */ 

def ine_bundle_inciex defines an entry in the bundle table. The type 
Cbunatt is a structure which contains elements corresponding to all the attri¬ 
butes. If the contents of a bundle table entry are changed, all subsequently 
drawn primitives use the information in the new entry, depending on the relevant 
aspect source flags. You should keep this fact in mind if you are designing 
display list traversal algorithms using SunCGI. 


In fact, SunCGI currently produces error 30 vtdren these individual attribute lunaion is called while the 
corresponding ASF is bundled. 
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typedef struct { 

Clintype line_type; 

Cfloat line_width; 

Cint line_color; 

Cmartype marker_type/ 

Cfloat inar3cer_size; 

Cint marker_color; 

Cintertype interior_style; 

Cint hatch_index; 

Cint pattern_index; 

Cint fill_color; 

Clintype periineter_type; 

Cfloat perimeter_width; 

Cint periineter_color; 

Cint text_font; 

Cprectype text_precision; 

Cfloat character_expansion; 

Cfloat character_3pacing; 

Cint text_color; 

} Cbunatt; 

In addition to the errors listed below, other errors can be detected if any of the 
attribute values are invalid, as specified in later sections. Results are undefined if 
an error occurs. 

ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 

VSOP, orVSAC. 

EBBD TBD I [31 ] Bundle table index out of range. 

SunCGI provides for specifying the style, width and color of lines which consti¬ 
tute polylines, circular arcs, and elliptical arcs. The functions do not affect the 
drawing of the perimeter of solid objects which are set by the perimeter func¬ 
tions. 

Cerror polyline_bundle_index(index) 

Cint index; /* polyline bundle index */ 

polyline_bundle_index sets the current polyline bundle index to the 
value of index. The contents of the polyline bundle index are line type , line 
width and line color. The line width specification mode and the line endstyle 
attributes are not included in the polyline bundle. If index is not defined, an 
error is generated, and the polyline_bundle_index does not change. If 
the ASF’s for any of these attributes is set to BUNDLED, the current values of these 
attributes are set to the contents of the bundle. 


Errors 

ENOTOPOP [5] 

CGI not in proper state CGI shall be in state VDOP, 
VSOP. orVSAC. 


EBADLINX [33] 

Polyline index is invalid. 


Errors 


4.2. Line Attributes 


Polyline Bundle Index 
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Line Type 


Errors 


Line Endstyle (SunCGI 
Extension) 


Errors 


Line Width Specification 
Mode 


Cerror line_type(ttyp) 

Clintype ttyp; /* style of line */ 

line_type defines the line type for polylines. The enumerated type Clin¬ 
type contains values that correspond to valid line types. 

typedef enum { 

SOLID, 

DOTTED, 

DASHED, 

DASHED_DOTTED, 

DASH_DOT_DOTTED, 

LONG_DASHED 
} Clintype; 

The default line style is SOLID. The actual representation of a line on the screen 
is affected by the line endstyle . DASH_DOT_DOTTED actually has three dots 
between dashes. 

ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 

VSOP, or VS AC. 

EBTBUNDL [30] ASF is BUNDLED. 

Cerror line_endstyle(ttyp) 

Cendstyle ttyp; /* style of line */ 

line_endstyle determines how a textured (non-SOLID) line terminates. 

The enumerated type Cendstyle contains values that correspond to valid line 
end styles. 

typedef enum ( 

NATURAL, 

POINT, 

BEST_FIT 
) Cendstyle; 

If the endstyle selected is NATURAL, the last component of the line texture (for 
example, a dash or a dot) which can be completely drawn is drawn. Blank space 
at the end of the line may cause the line to not appear as long as specified by the 
starting and ending coordinates. If the endstyle selected is POINT, the last point 
of the line is drawn whether it is appropriate or not. In this case, the endpoints of 
the line always appear on the screen. If the endstyle selected is BEST_Frr, the last 
point is always drawn but is extended as far back as the last space if appropriate. 
However, the BEST_FIT endstyle may shorten the space between the last element 
of the line and the element preceding the last element by one in order to guaran¬ 
tee that the line ends on a drawn point. The default endstyle is BEST_FIT. 

ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 
VSOP, orVSAC. 
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Cerror line_wid.th_specification_mode <mode) 

Cspecmode mode; /* pixels or percent */ 

line_width_specif ication_mode allows the line_width to be 
specified in pixels or as a percentage of VDC space according to the value of 
mode The enumerated type Cspecmode contains values that correspond to line 
width specification modes. 

typedef enum { 

ABSOLUTE, 

SCALED 
} Cspecmode; 

If the line width specification mode is changed from ABSOLUTE to SCALED, the 
change in the line width will probably be dramatic. The default line width 
specification mode is SCALED. 

If multiple view surfaces are active, the line width is scaled separately for each 
view surface. 

Errors ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 

VSOP.orVSAC. 

Line Width Cerror line_width (index) 

Cfloat index; /* line width */ 

line_width determines the width of the lines composing polylines, circular 
arcs, etc. If the line width specification mode is SCALED, index is expressed in 
percent of vdc space and if the x and y dimensions are different, the width is 
calculated on the basis of the range of the x coordinate of VDC space. If the 
parameter setting would result in a line less than one pixel wide, the line width is 
displayed as one pixel wide. The default line width is 0.0 (SCALED). 


Errors 

ENOTOPOP [5] 

CGI not in proper state CGI shall be in state VDOP, 
VSOP, orVSAC. 


ebtbundl [30] 

ASF is BUNDLED. 


ebdwidth [34] 

Width must be nonnegative. 

Line Color 

Cerror line_color(index) 

Cint index; /* line color */ 


line_color demrmines the color of the lines, index selects an entry in the 
color lookup table. The default value of index is 1. An error is detected if index 
is not between 0 and 255. 

Errors 

ENOTOPOP [5] 

CGI not in proper state CGI shall be in state VDOP, 
VSOP, orVSAC. 


EBTBUNDL [30] 

ASF is BUNDLED. 


ECINDXLZ [35] 

Color index is less than zero. 
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4.3. Polymarker Attributes 


Polymarker Bundle Index 


Errors 


Marker Type 


Errors 


Marker Size Specification 
Mode 


EBADCOLX [36] Color index is invalid. 

The type, size and color of markers (the components of polymarkers) are con¬ 
trolled by the following functions. 

Cerror polyinarker_bundle_ind.ex(index) 

Cint index; /* polymarker bundle index */ 

polymarker_bundle_index sets the current polymarker bundle index to 
the value of index . The contents of a polymarker bundle are marker type , 
marker size and marker color . JThe marker size specification mode function is 
not included in the polymarker bundle. If index is not defined, an error is gen¬ 
erated, and the polymarker bundle index does not change. If the ASF’s for any of 
these attributes is set to BUNDLED, the current values of these attributes are set to 
the values of the corresponding attribute in the bundle. 

ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 
VSOP, or VSAC. 

EBADMRKX [37] Polymarker index is invalid. 

Cerror marker_type(ttyp) 

Cmartype ttyp; /* style of marker */ 

marker_type sets the marker type. The enumerated type Cmartype con¬ 
tains values that correspond to valid marker types. 

typedef enum { 

DOT, 

PLUS, 

ASTERISK, 

CIRCLE, 

X 

} Cmartype; 

Note that all marker types appear as a point when the marker size is very small. 
The default marker type is DOT. 

ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 
VSOP, or VSAC. 

EBTBUNDL [30] ASF is BUNDLED. 


Cerror marker_si2e_specification_mode(mode) 

Cspecmode mode; /* pixels or percent */ 

inarker_size_specif ication_inode allows the marker size to be 
specified in pixels or as a percentage of VDC space according to the value of 
mode . The enumerated type Cspecmode contains values that correspond to 
valid marker size specifications. 
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typedef enum { 

ABSOLUTE, 

SCALED 
} Cspecmode; 

The default marker size specification mode is SCALED. 


Errors 

ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 

VSOP.orVSAC. 

Marker Size 

Cerror marker_size(index) 

Cfloat index; /* marker size */ 

marker_size sets the size of the mariker/ieig/rf znd marker width. index is 
expressed in percent of VDC space. The default marker size is 4.0 percent of VDC 
space. If the marker size becomes very small, markers of all types are displayed 


as points. An error is detected if index is negative. 

Errors 

ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 

VSOP.orVSAC. 

EBADS12E [38] Size must be normegative. 

Marker Color 

Cerror marker_color(index) 

Cint index; /* marker color */ 

marker_color determines the color of the markers, index selects an entry in 
the color lookup table. An error is detected if index is not between 0 and 255. 
The default marker color is 1. 

Errors 

ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 

VSOP,orVSAC. 

EBTBUNDL [30] ASF is BUNDLED. 

ECINDXLZ [35] Color index is less than zero. 

EBADCOLX [36] Color index is invalid. 

4.4. Solid Object Attributes 

The solid object attribute functions describe how all solid object primitives are 
filled (colored-in). There are three sets of solid object attribute functions: 

fill area attributes 

The fill area attribute functions determine the general method for filling solid 


geometrical objects. 
hatch and pattern attributes 

determines a pixel array for filling a polygon if the fill style is set to PAT¬ 
TERN. 

perimeter attributes 

detennine how the boundary of a geometrical object is displayed if the per¬ 
imeter visibility is ON. 
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Fill Area Bundle Index 


Errors 


Interior Style 


Errors 


4.5. Solid Interior Fill 
Attribute 


Cerror fill_area_bundle_index(index) 

Cint index; /* fill area bundle index */ 

fill_area_bundle_index sets the current fill area bundle index to the 
value of index . The contents of the fill area bundle are interior style ,fill color 
hatch index pattern index perimeter type perimeter width and perimeter color. 
The perimeter width specification mode and the pattern attributes are not 
included in the definition of the fill area bundle. If index is not defined, an error 
is generated, and the fill area bundle index does not change. If the ASF’s for any 
of these attributes is set to BUNDLED, the current value of the attribute is set to 
the value of the corresponding attribute in the bundle. 

ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 
VSOP,orVSAC. 

EBADFABX [39] Fill area index is invalid. 


Cerror interior_style(istyle, perimvis) 

Cintertype istyle; /* fill style */ 

Cflag perimvis; /* perimeter visibility */ 

interior_style sets thefor solid objects. The enumerated type 
Clintertype contains values that correspond to valid line types. 

typedef enum { 

HOLLOW, 

SOLIDI, 

PATTERN, 

HATCH 

} Cintertype; 

If fill style is set to SOLIDI, the solid object is filled with the current yi// color . 
If istyle is Kt to PATTERN or HATCH, the solid object is filled with the current 
PATTERN or HATCH Style. The PATTERN and HATCH styles are explained in the 
pattern attributes secdon. The defaultyi// style is HOLLOW. 

inter ior_style also determines whether the perimeter of the solid object is 
visible according to the value of perimvis (which must be ON or OFF). If per¬ 
imvis is OFF, the perimeter attributes have no effect. The default value of perim¬ 
eter visibility is ON. 

Be careful when using the interior style fimcdon to explicitly specify the per¬ 
imvis argument If you do not specify it, or set it to OFF, the geometrical output 
primitive may not be displayed because the interior style is HOLLOW. 

ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 
VSOP,orVSAC. 

The following section contains the description of a function that determines the 
color of an interior region if the fill style is not HOLLOW. 
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Fil! Color 


Errors 


4.6. Hatch and Pattern 
Attributes 


Cerror fill_color(color) 

Cint color; /* color for solid object fill */ 

f ill_color determines the color for filling solid objects, if the fill style is not 
set to HOLLOW. 

The default yi// style is HOLLOW, so changing the fill color will not have an effect 
without changing the interior style first. The default fill color is 1. An error is 
detected if fill color is not between 0 and 255. 

ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 
VSOP,orVSAC. 

ECINDXLZ [35] Color index is less than zero. 

EBADCOLX [36] Color index is invalid. 

Geometrical primitives can be filled with 2D arrays of color values called pat¬ 
terns. SunCGI supports pre-defined as well as user-defined patterns. The 
definition of patterns is stored in the pattern table . Each entry in the pattern 
table consists of a 2D array of color values and the x and y dimensions of the 
array. The starting position (upper left-hand comer) of the pattern is determined 
by the pattern reference point . 

Two types of patterns are available: PATTERNS and HATCHes. PATTERNS can be 
scaled and translated. HATCHes can’t and simply fill the geometrical output 
primitives with pixel arrays. 

The following example program illustrates how to change the appearance with 
the individual attribute ftmetions. The program draws a polygon and fills it with 
a pattern. 
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- 

#include <cgidefs.h> 

Ccoor box[5] = { 10000,10000 , 

10000,20000 , 

20000,20000 , 

20000,10000 , 

10000,10000 }; 

Cint pattern[16] = { 50, 75, 100, 125, 

150, 0, 0, 175, 

200, 0, 0, 225., 

250, 275, 300, 325 }; 

main () 

{ 

Ccoorlist boxlist; 

Cint dx = 250, dy = 250, index - 2, name; 

Cvwsurf device; 

boxlist.n = 5; 
boxlist.ptlist = box; 

NORMAL_VWSURF(device, PIXWINDD); 

open_cgi(); 

open_vws(&name, ^device); 

interior_style(PATTERN, ON); 
pattern_table(index, 4, 4, pattern); 
pattern_index(index); 
pattern_size(dx, dy); 
polygon(fiboxlist); 

sleep(10); 

close_vws(name); 
close_cgi(); 

} 

^ _ ^ 




Hatch Index 


Errors 


Figure 4-2 Example Program with Bundled Attributes 


Cerror hatch_index(index) 

Cint index; /* HATCH index in the pattern table */ 

hatch_index derermines which entry in the pattern table is used to fill solid 
objects when the^ style is set to HATCH. The default hatch index is 0. An 
error is generated if index points to an undefined entry in the pattern table. 


ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 

VSOP,orVSAC. 
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EBTBUNDL [30] ASF is BUNDLED. 

ESTYLLEZ [42] Style (pattern or hatch) index is less than zero. 

ENOP ATNX [43] Pattern table index not defined. 

Pattern Index Cerror patterrt_irtdex (index) 

Cint index; /* PATTERN index in the pattern table */ 

pattern_index determines which index in the pattern table is used to fill 
solid objects when th&fill style is set to PATTERN. The default pattern index is 
1. An error is generated if index points to an undefined entry in the pattern table. 


Errors 

ENOTOPOP [5] 

CGI not in proper state CGI shall be in state VDOP, 
VSOP,orVSAC. 


EBTBUNDL [30] 

ASF is BUNDLED. 


ESTYLLEZ [42] 

Style (pattern or hatch) index is less than zero. 


ENOP ATNX [43] 

Pattern table index not defined. 


Pattern Table 


Errors 


Cerror pattern_table(index, m, n, colorind) 

Cint index; /* entry in table */ 

Cint m, n; /* number of rows and columns */ 

Cint *colorind; /* array containing pattern */ 

pattern_table defines an entry in the pattern table, index defines the entry 
in the table (which must be less fiian 50). An error is generated if index is out¬ 
side the bounds of the pattern table. m and n define the height and width of the 
pattern (in pixels). The array pointed to by the argument colorind contains the 
actual pattern row-wise ftom the upper left. For monochrome view surfaces, all 
nonzero entries in colorind are treated as I when used. The maximum 
number of elements in a pattern (m x n) is MAXPATSEE. 

Pattern 0 is initially defined to be a 3 x 3 matrix which is set to zero at the 
comers and one elsewhere. Pattern 0 produces simple cross-hatching. Pattern 1 
(which produces a polka-dot pattern) is initially defined to be a 3 x 3 matrix 
which is set to 1 at the center and 0 elsewhere. 


ENOTOPOP [5] 

CGI not in proper state CGI shall be in state VDOP, 
VSOP.orVSAC. 

EPATARTL [40] 

Pattern array too large. 

EPATSZTS [41] 

Pattern size too small. 

ESTYLLEZ [42] 

Style (pattern or hatch) index is less than zero. 

EPATITOL [44] 

Pattern table index too large. 


Pattern Reference Point Cerror pattern_reference_point (begin) 

Ccoor *begin; 

pattern_reference_point defines the point in vdc space where the 
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Errors 


Pattern Size 


Errors 


Pattern with Fill Color 
(SunCGI Extension) 


4.7. Perimeter Attributes 


Perimeter Type 


pattern box begins. The pattern is then replicated over all VDC space. The upper 
left-hand comer of the pattern box is determined by begin . The default pattern 
reference point is (0, 0). pattern_ref erence_point has no effect if the 
interior style is not set to PATTERN. 

ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 

VSOP.orVSAC. 

Cerror pattern_si 2 e(dx, dy) 

Cint dx, dy; /* size of pattern in VDC space */ 

pattern_size defines the size of the pattern array in VDC coordinates, dx 
and dy determine the size of an elemem of the pattern in VDC space. 
pattern_size therefore allows you to ‘stretch’ the pattern to a certain size. 

If dx OTdy would result in pattern elements less than one pixel wide, 1 is used. 

If the pattern size is larger than the bounds of screen space, the effective pattern 
size is the size of VDC space. The default pattern size is (300,300). 

ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 
VSOP, or VSAC. 

Cerror pattern_with_fill_color(flag) 

Cflag flag; /* ON to use nonzero pattern 
elements as fill color */ 

Binary patterns allow the same pattern to be applied in different colors, without 
redefining the pattern array. pattern_with_f ill_color sets a non¬ 
standard CGI state pattern with fill color . The default pattern with fill color is 
OFF and each color value in a pattern table entry is used verbatim, as in standard 
CGI. When a pattern is used whileis ON, the pattern is considered to be a 
2D array of flags: where the pattern element is nonzero, the current fill color is 
used, instead of the actual value of the pattern element (When pattern with fill 
color is zero, a zero color index is used, just as when the flag is OFF.) 

The following sections contain descriptions of functions that determine the per¬ 
imeter attributes perimeter type , perimeter width , perimeter width specification 
mode and perimeter color. 

Cerror perimeter_type(ttyp) 

Clintype ttyp; /* style of perimeter */ 

perimeter_type defines the perimeter type for solid objects. The 
enumerated type Clintype contains values that correspond to valid perimeter 
types. 
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typedef enum { 

SOLID, 

DOTTED, 

DASHED, 

DASHED_DOTTED, 

DASH_DOT_DOTTED, 

LONG_DASHED 
} Clintype; 

The default perimeter style is SOLID. Notice that there is no ending style for per¬ 
imeter. The endstyle is controlled by the line_endstyle function. 

As mentioned previously, control of the drawing of the borders of solid objects is 
under the control of the perimeter attribute functions, not the line attribute func¬ 
tions. However, the two sets of functions take the same values. The perimeter 
attributes are essentially the same as the line attributes except that they affect the 
borders of solid attributes. The appearance of a perimeter can be similar to a line 
especially if interior style is set to HOLLOW. Perimeter attribute functions have 
no effect if the perimeter visibility is set to OFF. 

Errors ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 

VSOP, orVSAC. 

EBTBUNDL [30] ASF is BUNDLED. 


Perimeter Width Cerror perimeter_width (width) 

Cfloat width; /* perimeter width */ 

perimeter_width determines the width of the perimeters of solid objects. 
index can be expressed in percent of VDC space or pixels. If the perimeter width 
specification mode is set to SCALED and the x and y dimensions are different, the 
perimeter width is calculated on the basis of the range of the x coordinate of 
VDC space. If the parameter setting would result in a perimeter less than one 
pixel wide, the perimeter width is displayed as one pixel wide. The default per¬ 
imeter width is 0.0 (SCALED). 

Errors ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 

VSOP.orVSAC. 

EBTBUNDL [30] ASF is BUNDLED, 

EBDWIDTH [34] Width must be noimegative. 

Perimeter Width Specification Cerror perimeter_width_specif ication__mode (mode) 

Mode Cspecmode mode; /* pixels or percent */ 

periitieter_width_specif ication^mode allows the 
periineter_width to be specified in pixels or as a percentage of VDC space 
according to the value of mode (which can either be ABSOLUTE or SCALED). If 
the perimeter width specification mode is changed from ABSOLUTE to SCALED, 
the change in the line width will probably be dramatic. The default perimeter 
width specification mode is SCALED. 
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Errors 


Perimeter Color 


Errors 


4.8. Text Attributes 


Text Bundle Index 


Errors 


Text Precision 


ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 
VSOP, or VSAC, 

Cerror perimeter_color(index) 

Cint index; /* perimeter color */ 

perimeter_color determines the color of the perimeters, index selects an 
entry in the color lookup table. The default value of index is 1. An error is 
detected if index is not between 0 and 255. 


ENOTOPOP [5] 

CGI not in proper state CGI shall be in state VDOP, 
VSOP, or VSAC. 

EBTBUNDL [30] 

ASF is BUNDLED. 

ECINDXLZ [35] 

Color index is less than zero. 

EBADCOLX [36] 

Color index is invalid. 


SunCGI provides a variety of functions for determining how text is written to 
the screen. The most important text attribute is text precision. If text precision 
is set to STRING, firmware characters are used. The fonts, size, spacing, and 
alignment of firmware are more limited than characters drawn with text preci¬ 
sion set to a value other than STRING. Therefore, calls to text attribute fonctions 
regulating these aspects of text drawing have no effect when text precision is set 
to STRING. 

Cerror text_bundle_index(index) 

Cint index; /* text bundle index */ 

text_bundle_index sets the current text bundle index to the value of index. 
The contents of the text bundle index are text font text precision , character 
expansion factor , character spacing , and text color. The character height 
character orientation character path text alignment and fixed font are not 
included in the definition of the text bundle. If index is not defined, an error is 
generated, and the text bundle index does not change. If the ASF’s for any of 
these attributes are set to BUNDLED, the current values of these attributes are set 
to the contents of the bundle. 

ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 

VSOP. or VSAC. 

EBADTXTX [45] Text index is invalid. 

Cerror text_precision(ttyp) 

Cprectype ttyp; /* text type */ 

text_precision controls the precision with which text is displayed. The 
enumerated type Cprectype contains values that correspond to valid text pre¬ 
cisions. 
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Errors 


Character Set Index 



Errors 


typedef enuiu { 

STRING, 

CHARACTER, 

STROKE 
} Cprectype; 

If the text precision is set to STRING, the firmware character set is used. Note; 
firmware characters cannot be scaled or rotated. 

Characters are clipped, but not in parts (that is, if any portion of the character 
exceeds the clipping boundary the whole character is clipped). If the text preci¬ 
sion is set to CHARACTER, software generated characters are employed and char¬ 
acters are clipped, but not in parts. All text attributes have a visible elTect on 
software generated characters. If the text precision is set to STROKE, the CHAR¬ 
ACTER precision capabilities are enabled and characters are clipped in parts. The 
default text precision is STRING. 

ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 
VSOP.orVSAC. 

EBTBUNDL [30] ASF is BUNDLED. 

Cerror character_3et_index(index) 

Cint index; /* font set */ 

character_set_index selects a set of fonts. Although SunCGI supports 
this function, only set number 1 is defined. Calls to character_set_index 
with index assigned to a value other than 1 are ignored. 

ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 
VSOP, orVSAC. 


Text Font Index 


Errors 


Cerror text_font_index(index) 

Cint index; /* font */ 

text_f ont_index determines the current font. A list of available fonts and 
their availability when text precision is set to STRING is given in Table 4-3. A 
warning about the SYMBOL font: undefined characters are displayed as bugs (the 
six-legged kind). The default font is STICK. 


ENOTOPOP [5] 

EBTBUNDL [30] 
ETXTFLIN [47] 


CGI not in proper state CGI shall be in state VDOP, 
VSOP, orVSAC. 

ASF is BUNDLED. 

Text font is invalid. 
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Table 4-3 Available Fonts 


Font 

String Precision 

ROMAN 

Yes 

GREEK 

Yest 

SCRIPT 

Yes 

OLDENGLISH 

No 

STICK 

Yes 

SYMBOLS 

No 


t displayed as STICK font 


Character Expansion Factor Cerror character_expansion_factor (efac) 

Cfloat efac; /* width factor */ 

character_expansion_f actor determines the widih-to-height ratio of 
characters. If efac is greater than 1 the characters appear fatter than they are 
wide. If efac is less than 1 the characters appear slimmer than they are wide. 
The default character expansion factor is 1.0. An error is generated if efac is 
less than 0.01 or greater than 10. 

Errors ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 

VSOP, orVSAC. 

EBTBUNDL [30] ASF is BUNDLED. 

ECEXFOOR [48] Expansion factor is out of range. 


Character Spacing Cerror character_spacing(spcratio) 

Cfloat spcratio; /* spacing ratio */ 

character_spacing sets the spacing between characters based on the height 
of the characters. The amount of space between characters is obtained by multi¬ 
plying the character height by spcratio . The default character spacing factor is 
0.1. An error is generated if spcratio is less than -10 or greater than 10. 

Errors ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 

VSOP,orVSAC. 

EBTBUNDL [30] ASF is BUNDLED. 

ECEXFOOR [48] Expansion factor is out of range. 

Character Height Cerror character_height (height) 

Cint height; /* height in VDC */ 

The character_height function determines the height of text in VDC units. 
The height is defined as the distance from the top to the bottom of the character. 

Notice that changing the character height implicitly changes the character spac¬ 
ing . 
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Errors 


Fixed Font (SunCGI 
Extension) 


Errors 


Text Color 


Errors 


Character Orientation 


The default character height is 1000. This may result in huge characters if VDC 
space is reset from its default range (0-32767). If the x and y dimensions of VDC 
space are difrerent, the height is calculated on the basis of the range of the x 
coordinate of VDC space. 

ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 
VSOP.orVSAC. 

EBTBUNDL 130] ASF is BUNDLED. 

ECHHTLEZ [49] Character height is less than or equal to zero. 

Cerror fixed__font (flag) 

Cint flag; /* fixed or variable width characters */ 

f ixed__font allows diaracters to be of fixed or variable size. Iffiag is 
nonzero, the characters are of uniform size, otherwise the characters are packed 
proportional to their actual sizes. If the character precision is STRING, this fimc- 
don has no effect By default SunCGI supports variable width characters. 

ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 
VSOP.orVSAC. 


Cerror text_color(index) 

Cint index; /* color */ 

text_color determines the color of the text index selects an entry in the 
color lookup table. The default value of index is 1. An error is detected if index 
is not between 0 and 255. 


ENOTOPOP [5] 

EBTBUNDL [30] 
ECINDXLZ [35] 
EBADCOLX [36] 


CGI not in proper state CGI shall be in state VDOP, 
VSOP,orVSAC. 

ASF is BUNDLED. 

Color index is less than zero. 

Color index is invalid. 


Cerror character_orientation(xbase, ybase, xup, yup) 

Cfloat xbase, ybase, xup, yup; 

/* character base and up vectors */ 

char acter_orientat ion specifies the skew and direcdon of text The left 
side of the diaracter box lies on an invisible line called the character up vector 
whose slope is determined by andyi^p. The bottom of the diaracter box lies 
on an invisible line called the character base vector whose slope is determined 
hy xbase and yhore. 

If the character up vector and the character base vector are not orthogonal, die 
text is distorted. Calls to character_orientation have no effect if text 
precision is set to STRING. The default values for the character up vector and 
the character base vector are xbase - 1.0, ybase « 0.0, xup - 0.0, and yup = 
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Errors 


Character Path 


Errors 


Text Alignment 


1 . 0 . 

The character up vector and the character base vector influence the character 
path and the character alignment. For example, if xbase = -1,0 and the character 
path is RIGHT, the text is written to the left. 

ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 
VSOP.orVSAC. 

ECHRUPVZ [50] Length of character up vector or character base vector is 
zero. 


Cerror character_path(path) 

Cpathtype path; /* text direction */ 

character_path specifies the direction in which text is written. The 
enumerated type Cpathtype contains values that correspond to valid character 
paths. 

typedef enum { 

RIGHT, 

LEFT, 

UP/ 

DOWN 

} Cpathtype; 

The actual effect of char act er_path depends on the character up vector 
and the character base vector, RIGHT specifies that the text is written in the 
direction of the character base vector . For example, if the direction of the char¬ 
acter base vector points left instead of right (xup - -1.0 instead of 1.0), the text 
will be written right-to-left instead of left-to-right which is the usual interpreta¬ 
tion of RIGHT. LEFT specifies that the text is written in the opposite direction of 
the character base vector. The character up vector and character base vector 
essentially change ftmctions when the character direction is set to UP or DOWN. 
UP specifies that the text is written in the direction of the character up vector , 
DOWN specifies that the text is written in the opposite direction of the character 
up vector . The default character path is RIGHT. 

ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 
VSOP.orVSAC. 

Cerror text_aligniaent (halign, valign, hcalind, vcalind) 
Chaligntype halign; /* horizontal alignment type */ 
Cvaligntype valign; /* vertical alignment type */ 

Cfloat hcalind, vcalind; 

/* continuous alignment indicators */ 

text_aligninent determines where the text is positioned relative to the start¬ 
ing point specified by the cl argument of the text or vdm_text function. 
halign determines where the character is placed in relation to the r component 
of the starting coordinate of the text position (specified by the cl argument of 
text). The enumerated type Chaligntype contains values that correspond to 
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valid horizontal alignments. 

typedef enum { 

LFT, 

CNTER, 

RGHT, 

NRMAL, 

CNT 

} Chaligntype; 

If the value of halign is LFT, tiw horizontal position of the text will begin at the 
left edge of the box enclosing die text Similarly, if the value of halign is RGHT, 
the horizontal position of the text will begin at die right edge of die box encloS' 
ing the text. If the value of halign is CNTER the horizontal position of the text 
will begin equidistant from the right and die left edges of the text box. NRMAL 
assigns die alignment based on the value of the character path (see Table 4-4). 

If the value of halign is CNT (continuous) die horizontal position of die text is 
determined by the argument hcalind. In this case, the text will begin hcalind 
fraction of the width of the text box from the left edge of the character box. The 
default value of halign is NRMAL. 

valign specifies where the character is placed in relation to the y component of 
the text position. The enumerated type C valign type contains values that 
correspond to valid vertical alignments. 

typedef enum { 

TOP, 

CAP, 

HALF, 

BASE, 

BOTTOM, 

NORMAL, 

CONT 

) Cvaligntype; 

If the value of valign is TOP, the vertical position of the text will begin at the top 
edge of the character box. If the value of valign is CAP, the vertical position of 
the text will begin at the cap line of the character.^^ Similarly, if die value of 
valign is BOTTOM, the vertical position of the text will begin at the bottom edge 
of the character box. If the value of valign is BASE, the vertical position of the 
text will begin at the baseline of the diaracter.^^ If the value of valign is HALF 
the vertical position of the text will begin equidistant from the top and the bottom 
edges of the character box. NORMAL assigns the alignment based on the value of - 
the character path (see Table 4-4). If the value of valign is assigned to CONT 
(continuous), the vertical position of the text is determined by the argument 
vcalind and will begin vcalind ftaction of the height of the character box from 
the bottom edge of the character box. The default value of valign is normal. 

Tbe cap line is defined w the invisible line OMTeqwnding to tbe top of the avenge diaracter within a 

font. 

The baseline is defined u the invisible line corresponding to the bottom of the average character within a 
font. The baseline does not neceaiarily correspond to the bonom of a character. For eM^l;^^ a the tail of a 
lower-case g extends below the baseline. 
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Table 4-4 Normal Alignment Values 


Character 

Path 

Horizontal 

Normal 

Vertical 

Normal 

RIGHT 

LEFT 

BASELINE 

LEFT 

RIGHT 

BASELINE 

UP 

CENTER 

BASEUNE 

DOWN 

CENTER 

TOP 


Errors 


ENOTOP OP 15] CGI not in proper state CGI shall be in state VDOP, 

VSOP.orVSAC. 


4.9. Color Attributes SunCGI supports only one color specification mode — INDEXED. This color 

specification mode means that die red, green, and blue values (hereafter referred 
to as RGB values) are obtained from a table known as the color lookup table . 

The initial values of the color lookup table are provided in Table 4-5. If the dev¬ 
ice is monochrome, nonzero color values are displayed as black; zero is 
displayed as white. 

Table 4-5 Default Color Lookup Table 


Index 

Color 

0 

black 

1 

red 

2 

yellow 

3 

green 

4 

c^an 

5 

blue 

6 

magenta 

7 

white 


Color Table Cerror color_table (istart, clist) 

Cint istart; /* starting address */ 

Ccentry *cli3t; /* color triples and number of entries */ 

color_table defines RGB entries into the color lookup table . The color 
lookup table is initialized based on the depth of the display frame buffer and the 
cmapsize field provided in the Cvwsurf structure provided to open_vws. A 
monochrome device has an imwiitable color map; non-zero color indices arc 
displayed as black, zero is displayed as white. A color device gets a color map 
segment with 8 entries if the cmapsize field is zero upon opening the view sur¬ 
face. The 8 default color values arc given in Table 4-5. l^er color maps are 
also initialized to evenly spaced RGB values. 

The structure Ccentry contains elements that describe a color map entry. 



sun 

micmyttam 


Version C of 17 March 1986 







Chapter 4 — Attributes 75 


typedef struct { 

unsigned char *ra; 
unsigned char *ga; 
unsigned char *ba; 

Cint n; 

} Ccentry; 

The tniniintim and maximum color table entries are treated specially by Pixwins 
and hence by SunCGI. If they are set to be the same value, the user’s values for 
these two entries are both ignored. They revert to the inverse of the normal 
values; entry 0 becomes white, die maximum entry becomes black. 

The argument istart determines the first entry in the color lookup table to be 
modified, the argument clist contains the color information for entry istart in 
terms of triples of values of numbers ranging between 0 and 255. The last field 
of clist reports how many entries are to be modified. An error is generated if 
either the indices to the color lookup table are out of range. 

Errors ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 

VSOP, orVSAC. 

ECINDXLZ [35] Color index is less than zero. 

EB ADCOLX [36] Color index is invalid. 

4.10. Inquiry Functions The attribute inquiry functions permit examination of the current attributes. 

Attributes are reported in groups corresponding to the class of output primitive 
which they modify. The argument to each inquiry function has its own structure 
type which has an element for each of the individual attributes (see Appendix D). 

Inquire Line Attributes Clinatt *inquire_line_attributes () 

/* returns a pointer to line attribute structure */ 

inquire_line_attributes reports the current line style , line width, line 
color , and polyline bundle index in die appropriate elements of the returned 
value of the functioa 

typedef struct { 

Clintype style; 

Cfloat width; 

Cint color; 

Cint index; 

} Clinatt; 

inquir e_line_attribute5 returns a NULL (not an error number) in case 
of errors. Errors are printed if the error warning mode is not set to NO_ACnON. 

Errors ENOTOP OP [5] CGI not in proper state CGI shall be in state VDOP, 

VSOP, orVSAC. 

Inquire Marker Attributes Cmarkatt *inquire_marker_attributes () 

/* returns a pointer to marker attribute structure */ 
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inquire_marker_attributes reports the current marker style , marker 
width , marker color , and polymarker bundle index in the appropriate elements 
of the returned value of the function. 

typedef struct { 

Cmartype type; 

Cfloat size; 

Cint color; 

Cint index; 

} Cmarkatt; 

inquire_marker_attributes returns a NULL (not an. error number) in 
case of errors. Errors are prinred if the error warning mode is not set to 
NO_ACnON. 

Errors ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 

VSOP.orVSAC. 

Inquire Fill Area Attributes Cf illatt *inquire_f ill_area_attributes () 

The current interior style , perimeter visibility ,fill color, hatch index , pattern 
index f fill area bundle index , perimeter style , perimeter width , and perimeter 
color can be obtained by using the inquire_f ill_attributes function. 

typedef struct { 

Cintertype style; 

Cflagtype visible; 

Cint color; 

Cint hatch_index; 

Cint pattern_index; 

Cint index; 

Clintype pstyle; 

Cfloat pwidth; 

Cint pcolor; 

) fillatt; 

inquire_f ill_area_attributes returns a NULL (not an error number) 
in case of errors. Errors are printed if the error warning mode is not set to 
N0_ACT10N. 

Errors ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 

VSOP.orVSAC. 

Inquire Pattern Attributes Cpatternatt *inquire_pattern_attributes () 

/* returns a pointer to pattern attribute structure */ 

inquire_pattern_attributes reports the current pattern index, raw 
count , column count, color list, pattern reference point, and pattern size. 
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Errors 


typedef struct { 

Cint cur_index; 

Cint row; 

Cint column; 

Cint *colorlist; 

Ccoor *point; 

Cint dx; 

Cint dy; 

} patternatt; 

inquire_pattern_attributes returns a NULL (not an error number) in 
case of errors. Errors are printed if the error warning mode is not set to 
NO_ACTION. 

ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 

VSOP, or VSAC. 


Inquire Text Attributes 



Errors 



Ctextatt *inquire_text_attributes{) 

/* returns a pointer to text attribute structure */ 

inquire_text_attributes reports the current/onf set, text bundle index, 
font, text precision , character expansion factor , character spacing , text color , 
character height , character base vector, character up vector , character path , 
and text alignment . 

typedef struct { 

■, Cint fontset; 

Cint index; 

Cint current_font; 

Cprectype precision; 

Cfloat exp_factor; 

Cfloat space; 

Cint color; 

Cint height; 

Cfloat basex; 

Cfloat basey; 

Cfloat upx; 

Cfloat upy; 

Cpathtype path; 

Chaligntype halign; 

Cvaligntype valign; 

Cfloat hcalind; 

Cfloat vcalind; 

) textatt; 

inquire_text_attributes returns a NULL (not an error number) in case 
of errors. Errors are piiiued if the error warning mode is not set to NO_AcnoN. 

ENOTOPOP [5] CGI not in proper state CGI shall be in state VDOP, 

VSOP, or VSAC. 
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Inquire Aspect Source Flags Cflaglist *inquire_aspect_souroe_flags () 

/* returns a pointer to text attribute structure */ 

inquire_aspect_source_f lags reports whether attributes are set indivi¬ 
dually by returning all of the values of the ASFs. The element n of the flaglist 
struct is set to 18. The definitions of each fiag are in Table 4-2. 

typedef struct { 

Cint n; 

Cint *nuin; 

Casptype *value; 

} Cflaglist; 

inquire_aspect_source_f lags returns a NULL (not an error number) in 
case of errors. Errors are printed if the error warning mode is not set to 
NO_ACnON. 


Errors 


ENOTOPOP [51 CGI not in proper state CGI shall be in state VDOP, 
VSOP,orVSAC. 
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Input 


CGI has a collection of functions for managing input devices. The design of these 
functions has two purposes: provide an interface close to the actual input device 
and maintain portability of applications. CGI accomplishes the first goal with dif¬ 
ferent input device classes and methods of extracting input values. The second 
goal is achieved through CGI’s model of logical input devices (LID), an abstrac¬ 
tion whereby logical input devices required by the CGI standard are mapped onto 
the physical devices available to a CGI implementation. This section will intro¬ 
duce some of the terms used in describing the functionality of the CGI input prim¬ 
itives. 

A CGI input device consists of a measure associated with a trigger. A measure 
is the current value of a logical input device. For example, the lC_LOCATOR dev¬ 
ice reports an x-y position. This device is useful for determining a position on 
the screen. A trigger is a physical device used by an operator to accept a current 
value . A trigger fire corresponds to an event on a physical input device. At the 
request of the application program, SunCGI associates a measure with a trigger. 
Table S-1 has a list of the five logical input devices available to SunCGI applica¬ 
tion programs and the available triggers. For example, a mouse button on a Sun 
workstation is a trigger that can be associated with a IC_IjOCATOR device. When 
the mouse button is pressed, the x-y position of the mouse is returned as the 
measure of the IC_LOCATOR input device. 

An input event is the information saved when a trigger fires. This includes die 
measure of a logical input device associated with a trigger. 
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Input Devices Offered by SunCGI 


Device 

Class 

Measure 

Trigger 

Number 

Trigger 

IC_LOCATOR 

x-y position in VDC 

2 

Left mouse button 


space. 

3 

Middle mouse button 



4 

Right mouse button 



5 

Mouse movementt 



6 

Mouse still^ 

IC_STROKE 

Array of x-y points in 

2 

Left mouse button 


VDC space. 

3 

Middle mouse button 



4 

Right mouse button 

IC.VALUATOR 

Normalized X position. 

2 

Left mouse button 



3 

Middle mouse button 



4 

Right mouse button 



5 

Mouse movement 



6 

Mouse still 

IC_CHOICE 

A non-negative integer 

2 

Left mouse button 


which represents a 

3 

Middle mouse button 


selection from a number 
of choices. Zero 
represents "no choice". 

4 

Right mouse button 

IC_STRING 

Character string. 

1 

Keyboard input ter¬ 
minated a carriage 




return. 


t The Mouse Movement trigger fires when the mouse moves. 

$ The Mouse Still trigger fires when the mouse does not move for one fifth 
of a second or more. 

The graphical method with which the measure of an input device is displayed is 
called tracking. SunCGI provides several methods of tracking for each input 
device. Table 5*3 has a list of track Qrpes available for each input device class. 
Tracking must be explicitly enabled for each device. 

Each input device can be in one of die five states described pictoiially in Figure 
S-1. The state of an input device determines the m anne r in which the application 
program retrieves the measure of the input device. The input functions that allow 
a change of state are listed next to the arrows indicating the state change. 

RELEASED 

Before an input device is initialized it is in the RELEASED state. Any input 
function (except initialization) will generate an error in this state. 

NO_EVENTS 

After an input device has been initialized it is in the NO_EV£NTS state. An 
application program can extract an input value of an input device in 
NO_EVENTS state. This will result in either the value that the device was 
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initialized with or the value the device had when it was in a state where it 
could process events. This is not necessarily die current measure of the 
device and does not change while the device is in this state. 

RESPOND_EVENT 

The RESPOND_EVENT State corresponds with synchronous communication 
between the process diat controls die input device and the application pro¬ 
gram. When an application program requests the measure of an input device 
in RESPOND_EVENT State, SunCGI blocks program execution until it can 
fulfill the request The request_input function will return when the 
trigger fires and the input request is satisfied or after a timeout period. The 
input device then reverts to NO EVENTS state. 

The function that requests input and puts the input device in 
RESPOND_EVENT State is request_input. When the trigger associated 
with an input device in RESPOND EVENT state fires, the measure of that input 
device is then stored in the request register as well as returned by the 
request_input function. 

REQUEST_EVENT 

The REQUEST_EVENT State corresponds with asynchronous communication 
between the process that controls the input device and the application pro¬ 
gram. When an application samples an input device, input handling and pro¬ 
gram execution continue in parallel. Either the requested trigger fires or an 
explicit request is made to disable event processing and return the device to 
NO_EVENTS state. 

When the trigger associated with an input device in REQUECT EVENT state 
fires, the measure of that input device is then stored in the request register , a 
buffer with one element per device. The request register can be then be read 
with get_last_requested_event. 

QUEUE_EVENT 

When a device is in QUEUE_EVENT mode, events associated with the indi¬ 
cated device are appended to the event queue , a first-in, first-out (FIFO) 
buffer shared by all input devices. After calling enable_events, the 
SunCGI application retains program control. While an input device is in 
queue^EVENT mode, events are simultaneously added to the event queue 
when the program executes. 

await_event returns the event at the head of the event queue. If the 
queue is empty, await_event will wait for the designate trigger to fire 
or a timeout The application program must process this queue in a timely 
fashion or it will overfiaw. T^ event queue can be flushed completely or 
for a specific device. The application program must make an explicit request 
to disable event queue processing and return an input device to N0_EVENTS 
state. 
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Figure 5-1 CGI Input State Model 


5.1. Input Device 
Initialization 


Initialize LID 


Before input can be processed, an input devices must be initialized and associ¬ 
ated with a trigger. Input device initialization requires at least one active view 
surface. Typically, the procedure for initializing an input device includes calls to 
the initiali 2 e_lid and associate liinctions which turn on an input dev¬ 
ice and associate it with a specific trigger. 

Cerror initialize_lid(devclass, devnum, ival) 
edevoff devclass; /* device type */ 

Cint devnum; /* device ntnnber */ 

Cinrep *ival; /* initial value of device measure */ 

initialize_lid initializes an input device and changes its state from 
RELEASED to NO_EVENTS. Hiis function must be called for an input device 
before it can be referenced by any other input function. The argument devclass 
specifies the desired Qrpe of input value, devnum indicates the number of the 
device within that class. The argument ival sets the initial measure of the dev¬ 
ice. 

The Cinrep structure contains different elements for each type of measure. The 
appropriate element of Cinrep must be set or an error will be generated. a 
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Errors 


Release Input Device 


Errors 


Associate 


typedef struct { 

Ccoor *xypt; /* LOCATOR */ 

Ccoorlist *points; /* STROKE devices */ 

Cfloat val; /* VALUATOR device */ 

Cint choice; /* CHOICE devices */ 

Cchar *string; /* STRING device */ 

Cpick *pick; /* PICK devices (unsupported) */ 

} Cinrep; 

For example, in a LOCATOR device initialization, the xyprfield of Cinrep must 
be set to the address of a Ccoor allocated by the application program before the 
X and y elements can be set See the example program in Figure 5-2. 

Notice that whenever a device is initialized, no associations vnth triggers are 
made. This must be done by having the application program call the appropriate 
functions. An error is generated by initializ e_lid if the device does not 
exist, if it is already initialized, or if the initial value is out of range. 


ENOTVSAC [4] 
EINDNOEX [80] 
EINDALIN [82] 
EBADDATA [95] 
ESTRSIZE [96] 


CGI not in proper state: CGI shall be in state VS AC. 

Input device does not exist 

Input device already initialized.^^ 

Contents of input data record are invalid. 

Length of initial string is greater than the implementation 
defined maximum. 


Cerror release_input_device(devclass/ devnum) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

release_input_device releases all associations between a device and its 
triggers, and removes all pending events for die device from the event queue. 
release_input_device changes the state of the specified input device 
from NO_EVENTS to RELEASED. An error is produced if devclass and devnum 
does not refer to an existing and initialized device. 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 
EINDNOEX [80] Input device docs not exisL 
EINDINIT [81] Input device not initialized. 

Cerror associate(trigger/ devclass, devnum) 

Cint trigger; /* trigger number */ 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 


The ANSI Aindard allows initialized input devices to be re-initialized. SunCGl does not because it is felt 
that re-initializatioD is usually a misuke. 
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Errors 


Set Default Trigger 
Associations 


Errors 


Dissociate 


as sociat e links a trigger with a specific device. The trigger numbers avail¬ 
able for each device are listed in Table 5-1. Multiple associations are allowed; 
however, some associations are not allowed (for example, IC_L0CAT0R may not 
be associated with the keyboard). 


The interaction between an IC_STROKE device and the trigger requires some addi¬ 
tional explanation. ICJSTROKE can only be associated with the mouse buttons. 
The first coordinate in the IC_STROKE array is entered when the mouse button is 
initially pressed, the last coordinate is entered when the mouse button is released. 
For IC_1 jOCATOR and IC_VALUATOR devices, the measure is reported when the 
mouse button is pressed. 


ENOTVSAC [4] 
EINDNOEX [80] 
EINDINIT [81] 
EINASAEX [83] 
EINAIIMP [84] 
EINTRNEX [86] 


CGI not in proper state: CGI shall be in state VS AC. 
Input device does not exist 
Input device not initialized. 

Association already exists. 

Association is impossible. 

Trigger does not exist 


Cerror set_default__trigger__a3soci.ations fdevclass/ devnum) 
Cdevoff devclass; /* device type */ 

Cint devnum; /* device niunber */ 

set_default_tr igger_associations associates a device with a 
default trigger. The default associations are listed in Table 5-2. The rules for 
trigger association are the same as those for the associate function. 

Table 5-2 Default Trigger Associations 


Device 

Class 

Trigger 

Number 

Trigger 

IC_LOCATOR 

5 

Mouse position 

IC_STROKE 

4 

Right mouse button 

IC__VALUATOR 

3 

Middle mouse button 

IC_CHOICE 

2 

Left mouse button 

IC_SrrRING 

1 

Keyboard 


ENOTVSAC [4] 

CGI not in proper state: CGI shall be in state VSAC. 

EINDNOEX [80] 

Input device does not exist 

EINDINIT [81] 

Input device not initialized. 

EINASAEX [83] 

Association already exists. 

EINTRNEX [86] 

Trigger does not exist. 
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Cerror dissociate (trigger# devclass, devnuin) 

Cint trigger; /* trigger number */ 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

dissociate removes the association between a trigger and a specified device. 
If dissociate is called wdiile diere are events pending in the event queue for 
the dissociated device, the pending events are discarded. 

Errors ENOTVS AC [4] CGI not in proper state: CGI shall be in state VS AC, 

EINDNOEX [80] Input device does not exist 
EINDINIT [81 ] Input device not initialized. 

EINNTASD [85] association does not exist 
EINTRNEX [86] Trigger does not exist. 

Set Initial Value Cerror 3et_initial_value (devclass# devnijm# value) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

Cinrep *value; /* device value */ 

set_initial_value sets the current measure of a specified device. This 
function resets the position of the track, if the track is appropriate and activated, 
set_initial_value also resets the request register. 

A pointer element of the Cinrep structure must be set to the address of an 
application program allocated area before the values can be set. For example, in 
Figure 5-2 toe following statements were necessary before an initial value could 
be assigned to toe LOCATOR device. 

cinrep lvalue; 
point.X = 16384; 
point.y * 16384; 
ivalue.xypt =» Spoint; 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 

EINDNOEX [80] Input device does not exist 

EIND INIT [81] Input device not initialized. 

EBADDATA [95] Contents of input data record are invalid. 

ESTRSIZE [96] Length of initial string is greater than the implementation 

defined maximum. 

Set VALUATOR Range cerror set_valuator_range (devnum# vmin, vmax) 

cint devnum; /* device number */ 

Cfloat vmin# vmax; /* limits of VALUATOR */ 

set_valuator_range specifies the limits of toe IC_VALUAT0R. Device 
coordinates are mapped into toe IC_valuator range. IC_valuaT0R events 
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Errors 


Track On 


Errors 


which are already on the event queue are not rescaled. These events must be 
dequeued with either the selective_f lush_of_event_queue function 
or flush_event_queue. 



ENOTVSAC [4] 
EINDNOEX [80] 
EINDINIT [81] 


CGI not in proper state: CGI shall be in state VS AC. 
Input device does not exist 
Input device not initialized. 


Cerror trac)c_on (devclass, devnum, tracktype, 
trackregion, value) 

Cdevoff devclass; /* device type */ 

Cint devnujn; /* device niiinber */ 

Cint tracktype; /* track number */ 

Ccoorpair *trackregion; /* window for tracking */ * 
Cinrep *value; /* device value */ 


Tracking functions determine how the measure of an input device is displayed on 
the view surface. Each class of devices has its own set of possible tracks (given 
in Table 5-3). Although SunCGI allows certain classes of devices to track 
simultaneously, all types of input devices are not allowed to track at once. 
Tracking is not provided in the NO_EVENTS state unless the track type is 
PRINTERS_FIST. 


track_on initiates track (or echo) for a specific device. The tracktype argu¬ 
ment specifies the type of track to be used. The trackregion argument is not 
used; the device tracks in all areas of the view surface. The argument value is 
used to initialize tracking. The track is initially displayed on the first view sur¬ 
face opened. 



The xypt element of the Cinrep stmcture must be set to the address of an appli¬ 
cation allocated Ccoor and die Ccoor’s x and y fields are set to position the 
cursor. The reference point for lC_srROKE echos 2 through 5 is the first point in 
the STROKE array. The reference point for STRINGJTRACK echo is the 
append_t ext concatenation point, and can be changed by calling text or 
append_text. 


ENOTVSAC [4] 

CGI not in proper state: CGI shall be in state VS AC. 

EINECHON [88] 

Track already on. 

EINETNSU [91] 

Track Qq)e not supported. 

EBADDATA [95] 

Contents of input data record are invalid. 

ESTRSIZE [96] 

Lengdi of initial string is greater than the implementation 
defined TnaTimnTti. 
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Table 5-3 Available Track Types 


Device 

Class 

Number 

Track Typet 

Description 

IC LOCATOR 

<0 

NO_ECHO 

Default cursor. 


1 

PRINTERS_FIST 

Designate the current position of the IC_LOCATOR device 
with a printer’s fist cursor. 

IC STROKE 

<0 

NO ECHO 

Default cursor. 


1 

PRINTERS_FIST 

Designate the current position of the ICJSTROKE device 
with a printer’s fist cursor. 


2 

SOUD_LINE 

Draw a line from the origin to the current position in the 
STROKE array. 


3 

X_UNE 

Draw a line from the jc -axis to the current position in the 
STROKE array. 


4 

Y_UNE 

Draw a line from the y -axis to the current position in the 
STROKE array. 


5 

RUBBER_BAND_BOX 

Designate the current position of the IC STROKE device 
with a rubber band line connecting the initial position 
and the current position in the STROKE array. 

IC VALUATOR 

^0 

NO_ECHO 

Default cursor. 


1 

PRINTERS_FIST 

Indicate the state of the 1C_VALUAT0R device with a 
printer’s fist cursor. 


2 

CTRINGJTRACK 

Display a digital representation of the current 
IC_VALUATOR value. 

IC CHOICE 

<0 

NO_ECHO 

Default cursor. 


1 

PRINTERS_nST 

Indicate die state of the IC_CHOlCE device with a 
printer’s fist cursor. 

IC STRING 

<0 

NOECHO 

Default cursor. 


1 

PRINTERS_nST 

Indicate the state of the IC_STRING device with a 
printer’s fist cursor. 


2 

SrrRING_TRACK 

Display the current STRING value. 


t The values listed in the Track Type column in Table 5-3 are contained in the enumerated type Cechotype 
returned in the Cstatelist structure by inquire_lid_state_list. They are not used by track_on 
to define a track type. 

Track Off Cerror track_off(devclass, devnum, tracktype, action) 

Cdevoff devclass; /* device tyF>e */ 

Cint devnum; /* device number */ 

Cint tracktype; 

Cfreeze action; 

track_of f terminates tracking for a specified input device. The tracktype and 
the action arguments are always ignored. 

Errors ENOTVS AC [4] CGI not in proper state: CGI shall be in state VS AC. 

EINDNOEX [80] Input device does not exist 
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E INDINIT 181] Input device not initialized. 


.2, Synchronous Input The synchronous input function request_input allows the application pro¬ 

gram to obtain the current measure an of input device. This function requires 
explicit identification of an input device (dirough the associate function). 

Figure 5-2 contains an example program that illustrates how to use the synchro¬ 
nous input functions to get i^ormation from an input device. First, a 
IC_LOCATOR device is initialized and associated with a trigger (the left mouse 
button). The tracking method fw the IC_LOCATOR is defined to be a printer’s fist. 
Then measure of the IC_LOCATOR is requested with a timeout period of ten 
seconds. If the trigger is activated during this period, request_input returns 
a valid measure in ivalue . Finally, the IC_LOCATOR is dissociated ftom the 
mouse button and released. The program exits. 
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Request Input 


♦include <cgidefs.h> 

♦define TEN_SECONDS (10 * 1000 * 1000) 

main () 

{ 

Cawresult stat; 

Ccoor point; 

Cinrep lvalue; 

Cint name; 

Cint trigger; 

Cvwsurf device; 

NORMAL_VWSURF(device, PIXWINDD); 
point .x =» 16384; 
point.y =» 16384; 
ivalue.xypt * Spoint; 

open_cgi(); 

open_vws(Sname, ^device); 

initialize_lid(IC_LOCATOR, 1, fiivalue); 
associate(2, IC_LOCATOR, 1); 

track_on(IC_LOCATOR, 1, 1, (Ccoorpair *)0, fiivalue); 
request__input (IC_LOCATOR, 1, TEN_SECONDS, 

&stat/ &lvalue, £trigger); 
if (stat VALID_DATA) 

printf("trigger activated at %d %d \n", 
ivalue.xypt->x, ivalue.xypt->y); 

else 

printf("trigger not activated \n"); 
dissociate (2, IC__LOCATOR, 1); 
release_input_device(IC_LOCATOR, 1); 

close_vws(name); 
close_cgi(); 

) 

s_ 


Figure 5-2 Example Program with LOCATOR Input Device 

Cerror request_input(devclass, devntun, timeout, 
valid, sample, trigger) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

Cint timeout; /* amount of time to wait for input */ 
Cawresult *valid; /* device status */ 

Cinrep *sample; /* device value */ 

Cint *trigger; /* trigger number */ 

request_input waits timeout microseconds for activation of a trigger associ¬ 
ated with a specific device. If timeout is negative, the request will wait forever. 
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request_input puts the input device in the RESPOND_EVENT state. If a 
trigger is activated within this period, the activating trigger and the device meas¬ 
ure are returned in the trigger and sample arguments respectively. If the trigger 
is not activated within this period, the current device measure is returned in the 
sample argument and trigger is set to zero. Before returning, the input device is 
reset to NO_EVENTS state. 

request_input returns a device status in the argument valid. This argument 
uses the enumerated type Cawresult (AWait Result) which contains values 
describing the state of an input device. 

typedef enuin { 

VALID_DATA, 

TIMED_OUT, 

DISABLED, 

WRONG__STATE, 

NOT_SUPPORTED 
} Cawresult; 

VALID_DATA indicates a trigger is activated within die specified timeout period. 
TIMED OUT indicates that a trigger was not activated with a specified period. 
WRONG STATE indicates SunCGI is not in state vsac. N0T_SUPP0RTED indi¬ 
cates the requested device is not a legal device. 

If the appropriate field of the sample argument is a pointer, it must be set to an 
application program allocated area. 

ENOTVSAC [4] CGI not in proper state; CGI shall be in state VSAC. 
EINDNOEX [80] Input device does not exist 
EINDINIT [81] Input device not initialized. 

EINEVNEN [94] Events not enabled. 

53. Asynchronous Input This section explains the asynchronous method of input device management 

where the application process and the input device process operate simultane¬ 
ously. The designated input device is sampled witii initiate_request and 
the measure of the input device is read wiA get_last_requested_input. 
Alternatively, the current measure of a device may be read with 
s amp1e_input, 

The example program in Figure E-2 demonstrates how to use the asynchronous 
input functions. 

Initiate Request Cerror initiate_request (devclass, devnum) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

initiate_request sets up a device so that the measure resulting fiom the 
next trigger activation will be placed in the request register. 
initiate__request puts the device in the REQUEST_EVENT state. It then 
returns to the calling function without waiting for a trigger activation. The value 
caused by the trigger activation can be obtained by the 
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Errors 


5.4. Event Queue Input 


get_last_requested_input function. 


ENOTVSAC [4] 
EINDNOEX [80] 
EINDINIT [81] 
EINNTASD [85] 


CGI not in proper state: CGI shall be in state VS AC. 
Input device does not exist 
Input device not initialized. 

No triggers associated with device. 


The event queue is a single FIFO buffer that holds events from input devices. 
Since die event queue has a fixed length, it must be processed in a tiinely fashion 
or it will overflow. Events can be removed finom the event queue in diree ways: 
the event at the head of die event queue can be processed with await_event; 
the entire event queue can be emptied with f iush_event_queue; and the 
events from a particular device can be removed from the event queue with 
select ive_f lush_of_event_queue. 

Figure 5-3 contains an example program that illustrates how to use the event 
queue input functions to get information from an input device. First, a IC STRING 
device is initialized and associated with a trigger (the keyboard). The tracking 
method for the IC_STRING is defined to be a string that echos the keyboard input 
on the bottom of the viewport The IC_STRING is put into the QUEUE_EVENT state 
with enable_events. After the trigger fires, the measure of the 1C_STRING 
device is determined with await_event. Finally, the LOCATOR is dissociated 
from the mouse button and released. The program then exits. 
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♦include <cgidefs.h> 

main (} 

{ 

Cawresult valid; 

Ccoor point; 

Cdevoff devclass “ IC_STRING; 

Ceqflow overflow; 

Cinrep ivalue; 

Cint devnum - 1; 

Cint name; 

Cint replost; 

Cint tiine_stamp; 

Cint timeout - (10 * 1000 * 1000); /* ten seconds */ 
Cint tracktype * 2; 

Cint trigger “I; 

Cmesstype message_link; 

Cqtype qstat; 

Cvwsurf device; 

NORMAL_VWSURF(device, PIXWINDD); 

point.X =• 16384; 

point.y = 16384; 

ivalue.xypt = &point; 

ivalue.string = "This is a string"; 

open_cgi(); 

open_vws(&name, Sdevice); 

initialize_lid(devclass, devnum, Sivalue); 
associate(trigger, devclass, devnum); 
track_on(devclass, devnum, tracktype, 

(Ccoorpair *)0, &ivalue); 
enable_events(devclass, devnum); 
await__event(timeout, fivalid, fidevclass, &devnum, 
&ivalue, &message_link, &replost, &time_stamp, 
&qstat, ^overflow); 
printf("%s\n", ivalue.string); 
disable_events(IC_STRING, devnum); 
dissociate (trigger, IC_STRING, devnian) ; 
release_input_device(IC_STRING, devnum); 

close_vw3(name); 
close_cgi(); 

} 



o 


Figure 5-3 Example Program with STRING Input Device 

o 
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Enable Events 


Errors 


Avpait Event 


Cerror enable_event3 (devclass/ devnuin) 

Cdevoff devclass; /* device type */ 

Cint devniom; /* device number */ 

enable__event s allows a device in NO_EVENTS state to put events on the 
event queue. enable_events puts the input device in the QUEUE_EVENT 
state. An error is generated if the device specified by devclass or devnwn does 
not exist or is not initialized. 


ENOTVSAC [4] 
EINDNOEX [80] 
EINDINIT [81] 
EIAEVNEN [93] 


CGI not in proper state: CGI shall be in state VSAC. 
Input device does not exist 
Input device not initialized. 

Events already enabled. 


Cerror await_event(timeout/ valid, devclass, devnum, 
measure, inessage_lin)c, replost, time_stamp, 
qstat, overflow) 

Cint timeout; /* input timeout period */ 

Cawresult *valid; /* status */ 

Cdevoff *devclass; /* device type */ 

Cint *devnum; /* device number */ 

Cinrep *measure; /* device value */ 

Cmesstype *message_link; /* type of message */ 

Cint *replost; /* reports lost */ 

Cint *time_stamp; /* time_stamp */ 

Cqtype *qstat; /* queue status */ 

Ceqflow *overflow; /* event queue status */ 

await_event processes die event at the head of the event queue, valid is set 
to WRONG_STATE if SiuiCGI is not in state vsAC. If the event queue is EMPTY, 
then await_event waits timeout microseconds for a trigger to be activated. If 
timeout is less than 0, SimCGI waits until a trigger is activated, valid is set to 
VALID_DATA if a trigger is activated within the specified timeout period and 
TIMED_OUT otherwise. 

If either the event queue is not empty or a trigger is activated, the class, number 
and value of the device generating the event are reported in the returned argu¬ 
ments devclass , devnum and measure . If the appropriate field of the measure 
argument is a pointer, it must be set to an application program allocated area. 

If two events on the event queue have the same trigger but different values, the 
argument messagejink is assigned to SIMULTANEOUS_EVENT_FOLLOWS; other¬ 
wise the argument messagejink is set to SINGLE_EVEl^r. The enumerated type 
Cmesstype contains die following values: 

typedef enum { 

SIMULTANEOUS_EVENT_FOLLOWS , 

SINGLE_EVENT 
} Cmesstype; 

The replost and time_stamp arguments should be ignored and are always zero. 
The remmed argument qstat reports the queue status after an event is removed 
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Errors 


Flush Event Queue 


Errors 


Selective Flush of Event 
Queue 


Errors 


from the head of the event queue. 

typedef enum { 

NOT_VALID, 

EMPTY, 

NON_EMPTY, 

ALMOST_FULL, 

FULL 
) Cqtype; 

qstat is set to EMPTY if the event queue has no pending events, qstat is set to 
NON_EMPTY if the event queue has events pending, but is not FULL or 
ALMOST_FULL. qstat is set to ALMOST_FULL if there is room for only one more 
event on the event queue, qstat is set to FULL if there is no room for more events 
on the event queue. 

The argument overflow indicates whether the event queue has overflowed or not. 
The enumerated type Ceqf low contains the following values: 

typedef enum { 

NO_OFLO, 

OFLO 

} Ceqflow; 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 
EINQOVFL [97] Input queue has overflowed. 

Cerror flush_event_queue() 

f lush_event_queue discards all events in the event queue. The purpose of 
f lush_event_queue is to return the event queue to a stable state (NO_OFLO). 
f lush_event_queue does not affect the state of input devices. This function 
should be used carefully to avoid throwing away mouse-ahead or type-ahead 
inputs. 

ENOTOPOP [5] CGI not in proper state CGI shall be in either in state 
VDOP,VSOP,orVSAC 


Cerror selective_flush_of_event_jqueue{devclass, devnum) 
Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

selective_f lush_of_event_queue discards all events in the event 
queue which were generated by a specified device. 
selective_f lush_of_event_^queue does not affect the state of the 
specified input device, devclass and devnum must refer to an existing and ini¬ 
tialized device or an error is produced. However, no error is returned if no events 
from die specified device are pending. 

ENOTOPOP [5] CGI not in proper state CGI shall be in either in state 
VDOP.VSOP,orVSAC. 
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o 

5^, Miscellaneous Input 
Functions 


Sample Input 



Errors 


Get Last Requested Input 


Errors 

o 


EINDNOEX [80] Input device does not exist 

EINDINIT [81] Input device not initialized. 

The functions described in this section can be used with several of the input dev¬ 
ice management techniques described in die previous sections. For example, 
sample_input can be used when a device is in either RESPONDJEVENT or 
QUEUE_EVENT State. Likewise, disable_event s can be used in either of 
these states. 

Cerror sainple__input (devclass^ devnum, valid, sample) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

Clogical *valid; /* device status */ 

Cinrep *sample; /* device value */ 

sample_input reports the current measure of the specified input device in the 
returned argument sample . The returned argument valid reports whether the 
device is initialized and prepared to receive an input, "nie current measure of the 
device may be set by a queued event, a requested event, or a device initialization 
depending on the state of the input device and the most recent trigger 
activation(s). See the introduction of this chapter for an explanation of the rela¬ 
tionship between the measure of an input device and the state of an input dev¬ 
ice. If the appropriate field of the sample argument is a pointer, it must be set to 
an application program allocated area. 

ENOTVS AC [4] CGI not in proper state: CGI shall be in state VSAC. 
EINDNOEX [80] Input device does not exist 
EINDINIT [81] Input device not initialized. 

Cerror get_last_req[uested._input (devclass, devnum, 
valid, sample) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device numloer */ 

Clogical *valid; /* device status */ 

Cinrep *sample; /* device value */ 

get_last_requested_input returns the contents of tiie request register. 
get_last_request ed_input is usually used witii 

initiate_request, but request_input also changes, the contents of the ' 
request register. The renimed argument valid indicates whether the device exists 
and is initialized. The returned argument sample reports the event in the request 
register. If no event is in the request register, the initial device value is reported. 

If tile appropriare field of the sample arguznent is a pointer, it must be set to an 
application program allocated area. 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 
EINDNOEX [80] Input device does not exist 
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EINDINIT [811 Input device not initialized. 

Disable Events Cerror disable__events {devclaas, devnum) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

disable_event s puts the input device in the NO_EVENTS state. If the device 
is in RESPOND_EVENT state, die specified device is returned to NO_EVENTS state; 
the measure of the device is not changed by disai)le_event s. If die device 
is in QUEUE_EVENT State, disable_events stops die specified device from 
putting events on the event queue. However, existing entries on the event queue 
are not removed and existing associations remain, devclass and devnum must 
refer to an existing and initialized device or an error is produced. 


Errors 

ENOTVS AC [4] CGI not in proper state: CGI shall be in state VSAC. 

EINDNOEX [80] Input device does not exist 

EIND IN IT [81 ] Input device not initialized. 

EINEVNEN [94] Events not enabled. 

5.6. Status Inquiries 

The current state of the input devices, triggers, and the event queue can be 
obtained by using the fimctions discussed in this section. 

Inquire LID State List 

Cerror inquire_lid_state_list(devclass, devnum, 
valid, list) 

Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

Clogical *valid; /* device supported at all */ 

Cstatelist *list; /* table of descriptors */ 


inquire_lid_state_list reports the status of a specific input device 
specified by devclass and devnum. The argument valid reports whether the dev¬ 
ice is supported at all. The list aigument reports the track, associations, state and 
measure of the device in the appropriate elements of list . When checking the 
elements of list , first check the state element — if state is RELEASED, the other 
elements of//rr are undefined. 


typedef struct { 

Clidstate state; 

Cpromstate prompt; 

Cackstate acknowledgement; 


Cinrep *current; 
Cint n; 

Cint *triggers; 
Cechotype echotyp; 
Cechostate echosta; 
Cint echodat; 

} Cstatelist; 


Errors 
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Inquire LID State 


Errors 


o 

Inquire Trigger State 


Errors 


ENOTVSAC [4] CGI not in proper state: CGI shall be in state VS AC. 
EINDNOEX [80] Input device does not exist 

Cerror inquire_lid__state (devclass, devnum, validf state) 
Cdevoff devclass; /* device type */ 

Cint devnum; /* device number */ 

Clogical *valid; /* device supported at all */ 

Clidstate *state; /* table of descriptors */ 

inquire_lid_state repoits tlw status of a specific input device specified by 
devclass and devnum. The argument valid reports whefiier the device is sup¬ 
ported at all. The state argument (of type Clidstate) reports the current state 
of the specified input device. 

typedef enum { 

RELEASE, 

NO_EVENTS, 

REQUEST_EVENT, 

RESPOND_EVENT, 

QUEUE_EVENT 
} Clidstate; 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 

EINDNOEX [80] Input device does not exist 

Cerror inquire_trigger_state<trigger, valid, list) 

Cint trigger; /* trigger number */ 

Clogical *valid; /* trigger state */ 

Ctrigstate *li3t; /* trigger description table */ 

inquire_trigger_state describes the binding between a trigger and an 
input device. If the state element of the returned argument list is INACTIVE, no 
associations have been made with the trigger. An error is generated if the trigger 
does not exist 

typedef struct { 

Cactstate state; /* state */ 

Cassoclid *aS30c; /* list of associations */ 

} Ctrigstate; 

ENOTVSAC [4] CGI not in proper state: CGI shall be in state VSAC. 
EINTRNEX [86] Trigger does not exist 


Inquire Event Queue State 



Cerror inquire_event_queue_3tate(qstat, qflow) 

Cqtype * qstat; /* queue state */ 

Ceqflow * qflow; /* overflow indicator */ 

inquire_event_queue_state reports the status of the event queue, qstat 
indicates whether any events are pending. The argument qflow reports if the 
event queue is overflowing. 
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typedef enum { 
NOT_VALID, 
EMPTY, 
NON_EMPTY, 
ALMOST_FULL, 
FULL 
} Cqtype; 

typedef enum { 
NO_OFLO, 
OFLO 

} Ceqflow; 



Errors 


ENOTVSAC [4] CGI not in proper state: CGI shall be in state VS AC. 
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Differences between SunCore and 

SunCGI 

This appendix provides an introduction to SunCGI for programmers who have 
programming experience with SunCore or graphics packages based on the ACM 
Core Graphics Specificatioa The three major differences between SunCore and 
SunCGI are in the areas of output primitives, segmentation, and input. While 
SunCore is generally a ‘higher-level’ package, SunCGI has capabilities which 
are not available in SunCore. 

The major differences in drawing objects ro the screen between SunCore and 
SunCGI are drat 

1. SunCGI does not support 3D primitives, and 

2. SunCGI does not have fioating-point world coordinates or image 
transforms, and, 

3. SunCGI does not support the concept of current position, and 

4. SunCGI does not support textured color lookup table for monochrome dev¬ 
ices. 

However, SunCGI provides a wider variety of geometrical and raster primitives, 
and more control over die drawing of text These differences are summarized in 
Table A-1, 


A.I. Output Primitives 



Table A-1 Difference in Output Primitives 


Feature 

SunCore 

SunCGI 

3D Output Primitives 

Yes 

No 

Current Position 

Yes 

No 

Textured Color Lookup Tables 

Yes 

No 

Polygons with Invisible Edges 

No 

Yes 

Circles and Ellipses 

No 

Yes 

Cell Arrays 

No 

Yes 

Character Dipping 

No 

Yes 
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Output Aspects of SunCore SunCGI does not support 3D output primitives, current position, or textured 

not Supported by SunCGI color lookup tables for monochrome devices. Since 3D output primitives are not 

supported, no shading or lighting fimctions are provided either. Furthermore, no 
rotation or translation functions are provided. Therefore, if you want to rotate a 
geometrical output primitive, these operations must be done by your application 
program. 

Since SunCGI does not maintain the current position of the output 'cursor’, rela- 
tive drawing fimctions such as polygon_rel_3 are not supported. However, 
the application programmer can implement this function by specifying all coordi¬ 
nates as a base register plus a constant. The base register can be used by die 
application program to maintain the value of the current posidoiL 

For monochrome devices, SunCore interprets the entries in the color lookup 
table with indices greamr than one as patterns. SunCGI interprets all color 
lookup table entries greater than zero as black. Patterns in SunCGI are explicitly 
specified in the pattern table and invoked by using the PATTERN or HATCH inte¬ 
rior styles. In addition, while patterns in SunCore are all 4 x 4 matrices, patterns 
in SunCGI have variable dimensions. 


Output Features of SunCGI SunCGI offers geometrical and raster primitives not available in SunCore, as 
not Available in SunCore well as increased control over the drawing of text SunCGI provides circles and 

ellipses. SunCGI also supports the cell array which is a raster array whose ele¬ 
ment size is a function of the screen size. SunCGI clips characters in parts if the 
text precision is set to STROKE. 


A.2. Segmentation 


A.3. Differences in Input 
Functions between 
SunCore and SunCGI 


SunCGI does not support segmentatioiL This effect influences the effect of attri¬ 
bute calls. In SunCore, some attributes (for example, highlighting) apply to 
entire segments. Since no concept of segmentation exists in SunCGI, these attri¬ 
butes are not offered. Furthermore, SunCGI does not allow the saving or restor¬ 
ing of segments to the screen, so screen repainting fimctions must be completely 
defined by the application program, unless die view surface is initialized as a 
retained view surface and is not resized. 

SunCore provides device-specific functions for setting input device parameters 
and reading input from them. SunCGI provides no device dependent calls. 
SunCGI has three methods for obtaining the measure of input devices 

1. by first activation (REQUEST EVENT), 

2. by most recent activation (RESPOND EVENT), or 

3. by mediating input requests through the event queue (QUEUE EVENT). 

Furthermore, SunCGI allows the explicit binding of triggers (physical input dev¬ 
ices) to logical input devices. 
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Unsupported Aspects of CGI 


SunCGl does not support certain optiortal aspects of the proposed draft ANSI CGI 
standard. Most notably SunCGI does not support the full constellation of nego¬ 
tiation functions or tracking. SunCGI does not allow the resetting of coordinate 
type, coordinate precision or color specification mode because to do so would 
greatly reduce the speed of application programs written in SunCGI. Further¬ 
more, SunCGI does not support echoing functions for input, but provides the 
tracking functions instead. 


Table B-i Unsupported Control Functions 

_ Function _ 

vdc_type 

vdc_pr e c i s io n__f o r_i n t ege r _po i n t s 

vdc_pr e c i s i o n_f o r_r e a l_p o in t s 

integer_precision 

real_precision 

index_precision 

color_selection_mode 

color_precision 

color_index_precision 

viewport_specification_jnode 

make_picture_current 


Table B -2 Unsupported Input Functions 

_ Function _ 

set_prompt_state 

set__acknowledgement__state 

echo_on 

echo_off 

echo_update 


The following SunCGI fuisctions are nonstandard (that is, are not in the stan¬ 
dards document) and are included to make CGI easier to use. In addition, 
SunCGI has non-standard view surface arguments for certain control functions. 
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Table B-3 Non Standard Control Functions 

Function 

open_cgi 

open__vws 

activate__vws 

deactivate_vws 

close_vws 

close_cgi 



Table B-4 Non Standard Attribute Functions 

_ Function _ 

define_bundle_index 
line_endstyle 
s e t_g 1 ob a l_^dr a wi ng_mo de 
pattern_with_fill_color 
fixed font 


The Cinrep structure contains a presently unsupported pick field, for compati¬ 
bility with future segment manipulation capabilities. 
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Type and Structure Definitions 


This appendix provides a list of the structures and enumerated types used by 
SunCGI functions. In addition, a list of usefiil constants defined in 
<cgiconstants .h> is given. 


/★devices*/ 
#define BWIDD 1 
#define BW2DD 2 
#define CGIDD 3 
#define PIXWINDD 4 
#define CGPIXWINDD 5 
#define GPIDD 6 
#define CG2DD 7 


#define VWSURF NEWFLG 1 


/* limits */ 

#define MAXVWS 5 
#define MAXTRIG 6 
#define MAXASSOC 5 
#define MAXEVENTS 1024 

♦define MAXAESSIZE 10 /* maximum number of AES table entries */ 

♦define MAXNUMPATS 50 /* maximum number of pattern table entries */ 

♦define MAXPATSIZE 256 /* maximum pattern size */ 

♦define MAXPTS 1024 /* maximum number of pts per polygon */ 

♦define MAXCHAR 256 /* maximum number of chars in a string */ 

♦define OUTFUNS 67 /* number of output functions */ 

♦define INFUNS 22 /* number of input functions */ 

♦define SMALL_CHAR 6 /* minimum character size */ 

♦define DEVNAMESIZE 20 

The type and structure definitions that follow can be found in the header file 
<cgidefs.h>. 

typedef enum { 

ACK_ON, 

ACK_OFF 
} Cackstate; 


typedef enum { 
ACTIVE, 
INACTIVE 
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} Cactstate; 


typedef enum { 

CLEAR, 

NO_OP, 

RETAIN 
} Cacttype; 

typedef enxim { 

INDIVIDUAL, 

BUNDLED 
} Casptype; 

typedef struct { 

Cint n; 

Cdevoff *class; 

Cint *assoc/ 

1 Cassoclid; 

typedef enum { 

VALID_DATA, 

TIMED_OUT, 

DISABLED, 

WRONG_STATE, 

NOT_SUPPORTED 
} Cawresult; 

typedef enum { 

BITNOT, 

BITTRUE 
} Cbitmaptype; 

typedef enum { 

TRANSPARENT, 

OPAQUE 
} Cbmode; 

typedef struct { 

Clintype line_type; 

Cfloat line_width; 

Cint line_color; 

Cmartype marker_type; 
Cfloat marker_3ize; 

Cint marker_color; 
Cintertype interior_style; 
Cint hatch_index; 

Cint pattem_index; 

Cint fill_color; 

Clintype perimeter_type; 
Cfloat perimeter_width; 
Cint perimeter_color; 

Cint text_font; 

Cprectype text_precision; 
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Cfloat character_expansion; 
Cfloat character_spacing; 

Cint text_color; 

} Cbunatt; 

typedef struct { 

unsigned char *ra; 
unsigned char *ga; 
unsigned char *ba; 

Cint n; 

} Ccentry; 

typedef enum { 

OPEN, 

CLOSE 
} Ccflag; 

typedef struct { 

Cint numloc; 

Cint numval; 

Cint numstrk; 

Cint numchoice; 

Cint numstr; 

Cint numtrig; 

Csuptype event_queue; 

Csuptype asynch; 

Csuptype coord_map; 

Csuptype echo; 

Csuptype tracking; 

Csuptype prompt; 

Csuptype acknowledgement; 
Csuptype trigger_manipulation; 
} Ccgidesctab; 

typedef enum { 

YES, 

NO 

} Cchangetype; 

typedef char Cchar; 

typedef enum ( 

NOCLIP, 

CLIP, 

CLIP_RECTANGLE 
1 Cclip; 

typedef entun { 

CHORD, 

PIE 

} Cclosetype; 
typedef enum { 
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REPLACE, 

AND, 

OR, 

NOT, 

XOR 

} Ccombtype; 

typedef struct { 

Cint x; 

Cint y; 

} Ccoor; 

typedef struct { 

Ccoor *ptlist; 

Cint n; 

} Ccoorlist; 

typedef struct { 

Ccoor *upper; 

Ccoor *lower; 

} Ccoorpair; 

typedef enum { 
IC_LOCATOR, 
IC_STROKE, 
IC_VALUATOR, 
IC_CHOICE, 
IC_STRING, 

IC_PICK 
} Cdevoff; 

typedef enum { 

E_TRACK, 

E_ECHO, 

E_TRACK_OR_ECHO, 
E_TRACK_AND_ECHO 
} Cechoav; 

typedef struct { 

Cinrep *echos; 

Cint n; 

} Cechodatalst; 

typedef enum { 
ECHO_OFF, 

ECHO_ON, 

TRACK_ON 
} Cechostate; 

typedef struct { 

Cechostate *echos; 
Cint n; 

} Cechostatelst; 
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typedef enum { 

NO_ECHO, 

PRINTERS_FIST, 

HIGHLIGHT, 

RUBBER_BAND_BOX, 

DOTTED_LINE, 

SOLID_LINE, 

STRING_ECHO, 

XLINE, 

YLINE 

} Cechotype; 

typedef struct { 

Cint n; 

Cechoav *eleinents; 
Cechotype *echos; 

} Cechotypelst; 

typedef enum { 

NATURAL, 

POINT, 

BEST_FIT 
} Cendstyle; 

typedef enum { 

NO_OFLO, 

OFLO 

} Ceqflow; 

typedef Cint Cerror; 

typedef enum { 
INTERRUPT, 
NO_ACTION, 

POLL 

} Cerrtype; 

typedef enum { 
CLIP_RECT, 

VIEWPORT, 
VIEWSURFACE 
} Cexttype; 

typedef struct { 

Cintertype style; 
Cflag visible; 

Cint color; 

Cint hatch_index; 
Cint pattern_index; 
Cint index; 

Clintype pstyle; 
Cfloat pwidth; 

Cint pcolor; 


Asun 


Version C of 17 March 1986 




116 SunCGI Reference Manual 


} Cfillatt; 

typedef enum { 

OFF, 

ON 

} Cflag; 

typedef struct { 

Cint n; 

Cint *num; 

Casptype *value; 

} Cflaglist; 

typedef float Cfloat; 

typedef enum { 

FREEZE, 

REMOVE 

} Cfreeze; 

typedef eniom { 

LFT, 

CNTER, 

RGHT, 

NRMAL, 

CNT 

) Chaligntype; 

typedef enum { 

NO_INPUT, 

ALWAYS_ON, 

SETTABLE, 

DEPENDS_ON_LID 

} Cinputability; 

typedef struct { 

Ccoor *xypt; /* LOCATOR */ 

Ccoorlist *point3; /* STROKE devices */ 
Cfloat val; /* VALUATOR device */ 

Cint choice; /* CHOICE devices */ 

Cchar *string; /* STRING device */ 

Cpick *pick; /* PICK devices */ 

} Cinrep; 

typedef int Cint; 

typedef enum { 

HOLLOW, 

SOLIDI, 

PATTERN, 

HATCH 

) Cintertype; 
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typedef struct 1 

Clogical sample; 
Cchangetype change; 

Cint numassoc; 

Cint *trigassoc; 

Clogical prompt; 

Clogical acknowledgement; 
Cechotypelst *echo; 

Cchar *cla3sdep; 
Cstatelist state; 

} Cliddescript; 

typedef enum { 

RELEASE, 

NO_EVENTS, 

REQUEST_EVENT, 

RESPOND_EVENT, 

QUEUE_EVENT 
) didst ate ; 

typedef struct { 

Clintype style; 

Cfloat width; 

Cint color; 

Cint index; 

} Clinatt; 

typedef enum { 

SOLID, 

DOTTED, 

DASHED, 

DASHED_DOTTED, 
DASH_DOT_DOTTED, 
LONG_DASHED 
} Clintype; 

typedef enum { 

L_FALSE, 

L_TRUE 
} Clogical; 

typedef struct { 

Cmartype type; 

Cfloat size; 

Cint color; 

Cint index; 

} Cmarkatt; 


typedef enum { 
DOT, 

PLUS, 

ASTERISK, 

CIRCLE, 
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X 

} Cmartype; 

typedef enure { 

SIMULTANEOUS_EVENT_POLLOWS, 
SINGLE_EVENT 

} Creesstype; 

typedef enure { 

RIGHT, 

LEFT, 

UP, 

DOWN 

} Cpathtype; 

typedef struct 1 

Cint cur_index; 

Cint row; 

Cint column; 

Cint *colorlist; 

Ccoor *point; 

Cint dx; 

Cint dy; 

} Cpatternatt; 

typedef struct { 

int segid; /* segment */ 
int pickid; /* pick id */ 

) Cpick; 

typedef struct pixrect Cpixrect; 

typedef enure { 

STRING, 

CHARACTER, 

STROKE 

1 Cprectype; 

typedef enure { 

PROMPT_OFF, 

PROMPT_ON 

} Cpromstate; 

typedef enure { 

NOT_VALID, 

EMPTY, 

NON_EMPTY, 

ALMOST_FULL, 

FULL 

} Cqtype; 

typedef enure { 

ABSOLUTE, 
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SCALED 
} Cspecmode; 

typedef struct { 

Clidstate state; 

Cpromstate prompt; 

Cackstate acknowledgement; 
Cinrep *current; 

Cint n; 

Cint *trigger3; 

Cechotype echotyp; 

Cechostate echosta; 

Cint echodat; 

} Cstatelist; 

typedef enum { 

NONE, 

REQUIRED_FUNCTIONS_ONLY, 
SOME_NON_REQUIRED_FUNCTIONS, 
ALL_NON_REQUIRED_PUNCTIONS 
} Csuptype; 

typedef struct { 

Cint fontset; 

Cint index; 

Cint current_font; 

Cprectype precision; 

Cfloat exp_factor; 

Cfloat space; 

Cint color; 

Cint height; 

Cfloat basex; 

Cfloat basey; 

Cfloat upx; 

Cfloat upy; 

Cpathtype path; 

Chaligntype halign; 
Cvaligntype valign; 

Cfloat hcalind; 

Cfloat vcalind; 

} Ctextatt; 

typedef enum { 

NOT_FINAL, 

FINAL 

) Ctextfinal; 

typedef struct { 

Cchangetype change; 
Cassoclid *numa3soc; 

Cint maxassoc; 

Cpromstate prompt; 

Cackstate acknowledgement; 
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Cchar *naine; 

Cchar *de3cription; 

} Ctrigdis; 

typedef struct { 

Cactstate state; 

Cassoclid *assoc; 

) Ctrigstate; 

typedef enum { 

TOP, 

CAP, 

HALF, 

BASE, 

BOTTOM, 

NORMAL, 

CONT 

1 Cvaligntype; 

typedef enum { 

INTEGER, 

REAL, 

BOTH 

) Cvdctype; 

typedef struct { 

Cchar screenname[DEVNAMESIZE]; /* physical screen */ 
Cchar windowname[DEVNAMESIZE]; /* window */ 

Cint windowfd; /* window file */ 

Cint retained; /* retained flag */ 

Cint dd; /* device */ 

Cint cmapsize; /* color map size */ 

Cchar cmapname[DEVNAMESIZE]; /* color map name */ 
Cint flags; /* new flag */ 

Cchar **ptr; /* CDI tool descriptor */ 

} Cvwsurf; 
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Error Messages 


This appendix lists the error messages in numerical order. Furtheimoie, the 
probable cause of each error is given in the sentences following the error. In 
addition to explaining the error message, an initial suggestion for corrective 
action is given. In the title for each group of errors, the range of error numbers is 
given in parentheses after the title. If your application program is not behaving 
as you want it to, but does not generate error messages, then the table at the end 
of this appendix which lists commonly encountered problems and frequent 
causes may be helpful. 

D.l. Successful Return (0) NO_ERROR [0] No error. 

D.2. State Errors (1-5) ENOTCGCL [1] CGI not in proper state: CGI should be in state CGCL . A 

call to open__cgi was attempted when cgi was already 
opeiL Elimination of the error can be accomplished by 
removing the offending call to open_cgi. 

ENOTCGOP [2] CGI not in proper state: CGI should be in state CGOP. 

Every function except open__cgi requires that CGI be 
open. If this error is received, make sure that your applica¬ 
tion program has called open_cgi, or that it has not 
recently called close^cgi 

ENOTVSOP [3] CGI not in proper state: CGI should be in state VSOP . 

The function which generated the error requires that at 
least one view surface be opea Corrective action would 
include either removing the most recent call to 
close_vws or by including a call to open_vws. 

ENOTVS AC [4] CGI not in proper state: CGI should be in state VSAC . 

The function which generated the error requires that at 
least one view surface be active. Corrective action would 
include either removing the most recent call to 
deactivate_vws or by including a call to 
activate^vws. 

ENOTOPOP [5] CGI not in proper state CGI should be in state CGOP, 

VSOP, or VSAC . The function which generated the error 
requires that SunCGI is at least initialized. If this error is 
received, make sure that your application program has 
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called open_cgi, or that it has not recently called 
close_cgi. 


D.3. Control Errors (10-16) EVSIDINV [10] 


ENOWSTYP [11] 


EMAXVSOP [12] 


EVSNOTOP [13] 


EVSISACT [14] 


EVSNTACT [15] 


EINQALTL [16] 


D-4. Coordinate Definition EBADRCTD [20] 

(20-24) 


EBDVIEWP [21] 


Specified view surface name is invalid. The view surface 
name specified by the name argument has never been 
opened or if it has been opened, it has since been closed. 
Corrective action involves opening the view surface or 
changing the value of the name argument 

Specified view surface type does not exist. The application 
program has specified a type of view surface which is not 
supported by SunCGI. Corrective action involves chang¬ 
ing die type of view surface. 

Maamum number of view surfaces already open . An 
attempt was made to open a view surface when the max¬ 
imum number of view surfaces is already open. Corrective 
action involves removing one call to open_vws. 

Specified view surface not open . An attempt was made to 
close a view surface which is already closed. Corrective 
action involves removing one call to close_vws. 

Specified view surface is active , An attempt was made to 
activate a view surface which is already activated. Correc¬ 
tive action involves removing one call to 
activate_vws. 

Specified view surface is not active. An attempt was made 
to deactivate a view surface which has already been deac¬ 
tivated. Corrective action involves removing one call to 
deactivate_vws. 

Inquiry arguments are longer than list . A call to inquiry 
negotiation function with indices greater than the number 
of supported functions was made. The returned list is 
always empty. Corrective action may be facilitated by 
obtaining die size of the list by using the 
inc[uire_device_class function. 

Rectangle deration is invalid . The application program 
has made a call to vdc_extent or 
device_viewport with the coordinates of both comers 
equal in the x or y dimensions or both. Corrective action 
involves changing one of the arguments to the function 
which generated die error so that the values of the two 
arguments are different in both the x and y dimensions. 

Viewport is not within Device Coordinates . A call to 
device_viewport has been made which specifies a 
viewport which is larger than the view surface. Corrective 
action involves makin g die arguments to 
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Output Attributes (SC¬ 
SI) 



ECLIPTOL [22] 


ECLIPTOS [23] 


EVDCSDIL [24] 


device_viewport less than the view surface size. The 
size of the view surface can be obtained by calling the 
inquire_physical_coorciinate_systein func¬ 
tion. 

Clipping rectangle is too large. The clipping rectangle 
wotdd exceed the boundaries of VDC space. Corrective 
action involves resetting the clipping rectangle to be 
within limits of VDC space. 

Clipping rectangle is too small . The clipping rectangle 
would define an area of screen space smaller than one 
pixel. The clipping rectangle remains unchanged. Since 
die occurrence of diis error is partially a function of the 
size of the view surface, dianging the size of the view sur¬ 
face may be a viable alternative to changing the size of the 
clipping rectangle. 

VDC space definition is illegal , One or more of the argu- 
nrents to the vdc_^extent function exceeds the accept¬ 
able limits (-32767 to 32767) or coordinates of the lower- 
left hand comer are greater than the coordinates of the 
upper-right hand comer. Corrective action involves 
digging the arguments to vdc_extent. 


EBTBDNDL [30] 


EBBDTBDI [31] 


EBTUNDEF [32] 


EBADLINX [33] 


EBDWIDTH [34] 


ASF is BUNDLED . Error 16 is generated when attempt¬ 
ing to call an individual attribute function when the attri¬ 
butes are specified by entries in the attribute environment 
table . Calls to these fimctions have no effect on the 
current attributes. Corrective action includes resetting the 
attribute environment selector to BUNDLED by using the 
set_attribute_environment_selector func- 
tiorL 

Bundle table index out of range. The entry in the bundle 
table exceeds the size of the table. The only corrective 
action is to change the value of the index argument. 

Bundle table index is undefined. The entry in the attribute 
environment table specified by the most recent call to 
s e t_at t r ibu t e_en vi r o nmen t _t ab le_i ndex 
has not been defined by SunCGI or the application pro¬ 
gram. 

Polyline index is invalid . The polyline bundle is not 
defined. Corrective action involves changing the index 
argument to polyline_bundle_index, or by 
defining the polyline bundle index. 

Width must be nonnegative. The width of a perimeter or 
line must be greater than or equal to zero. The current 
value of the perimeter width or line width remains 
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ECINDXLZ [35] 


EBADCOLX [36] 


EBADMRKX [37] 


EBADSIZE [38] 


EBADFABX [39] 


EPATARTL [40] 


EPATSZTS [41] 


ESTYLLEZ [42] 


ENOPATNX [43] 


unchanged. Changing the value of the width argument to a 
non-i^gative value will correct this error. 

Color index is less than zero . The value of the index 
argument to one of the attribute functions or the color 
entry in one of die bundles is negative. Corrective action 
involves changing the value of the color. 

Color index is invalid. The color index argument to one 
of the attribute functions or the color entry in one of the 
bundles is not defined in the colormap. Indices in the 
color lookt^ table must be between 0 and 2S5 for the Sim 
8<bit per pixel frame buffer. Any color specification out¬ 
side of this range is ignored. Corrective action involves 
changing the value of the color. 

Polymarker index is invalid . The polymarker bundle is 
not defined. Corrective action involves changing the 
index argument to polyitiarlcer_bundle_index, or 
by defining the polymarker bundle index. 

Size must be nonnegative . The size of a marker or line 
must be greater or equal to zero. The current value of the 
marker size remains unchanged. Changing the value of 
die size argument to a non-negative value will correct this 
error. 

Fill area index is invalid. The fill area bundle is not 
defined. Corrective action involves changing the index 
argument to fill_axea_bundle_index, or by 
defining the polymarker bundle index. 

Pattern array too large. The pattern array must contain 
less than 257 elements. The pattern is not entered into the 
pattern table. Corrective action involves designing a new 
pattern. 

Pattern size too small , The pattern size must be at least 
two-by>two. The pattern is not entered into the pattern 
table. Corrective action could include designing a new 
pattern which includes several replications of the original 
pattern. 

Style (pattern or hatch) index is less than zero. All 
indices in die pattern table must be positive. To fix this 
mistake, change the argument to the pattern_index or 
die hat ch__index or the entries in the bundle table. 

Pattern table index not defined . The argument to the 
hatch_index or pattern_index function or the 
entry bundle table should be reset to correspond to a 
defined value. 


sun 

micre«y«tan» 


Version C of 17 March 1986 




Appendix D — Ennr Messages 127 


EPATITOL [44] 


EBADTXTX [45] 


EBDCHRIX [46] 


ETXTFLIN [47] 


ECEXFOOR [48] 


ECHHTLEE [49] 


ECHRUPVZ [50] 


ECOLRNGE [51] 


D.6. 


Output Primitives (60- 
70) 


ENMPTSTL [60] 


EPLMTWPT [61] 
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Pattern table index too large. The index argument to 
pattern_table exceeded the bounds of the pattern 
table . The pattern is not entered into the pattern table . 
Redefining the pattern index to be between one and ten 
will eliminate the error. 

Text index is invalid. TTie text bundle is not defined. 
Q)iTective action involves changing file index argument to 
text_jDundle_index, or by defining the text bundle 
index. 

Character index is undefined . All other character indices 
besides 1 are undefined in SunCGI. Tlie new character 
index is simply ignored You are advised to ignore the 
character_index fiinction entirely. 

Text font is invalid . The text fonts range from 1 to 6. All 
other integers do not correspond to actual fonts. Correc¬ 
tive action involves changing the argument to the 
text_f ont_index function or resetting the font index 
in the text bundle 

Expansion factor is out cf range . The character expan¬ 
sion factor or the character space expansion factor would 
result in a character or a space which would exceed the 
boimds of the screen or would result in a character smaller 
than the limitations of file character drawing software. To 
eliminate this error, reset the offending value to within an 
acceptable range (0.1-2.0 are reasonable guidelines). 

Character height is less than or equal to zero . The char¬ 
acter height must be positive. Corrective action involves 
changing the argument to the character height function or 
the element of the text bundle. 

Length of character up vector or character base vector is 
zero . Both the character up vector and the character base 
vector must be nonzero. Corrective action involves chang¬ 
ing the arguments to the character_orientation 
fimction or the element of the text bundles. 

RGB values must be between 0 and255 . The red, green, 
and blue values are only defined between 0 and 255. The 
call to color__table which produced the error is 
ignored. Corrective action requires respecifying the values 
of the arguments to color_table. 

Number of points is too large . The number of points 
exceeds 255. Change the n element of the Ccoorlist 
structure to a value less than or equal to 255. 

polylines must have at least two points . Change the n ele¬ 
ment of the Ccoorlist structure to a value greater than 
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EPGMTHPT [62] 

EGPLISFL [63] 


EARCPNCI [64] 


EARCPNEL [65] 


ECELLATS [66] 


ECELLPOS [67] 

ECELLTLS [68] 
EVALOVWS [69] 

EPXNOTCR [70] 


or equal to 2 and add the corresponding points to the ptlist 
element. 

Polygons must have at least three points. Change the n 
element of the Ccoorlist structure to a value greater 
dian or equal to 3 and add the corresponding points to the 
ptlist element. 

Global polygon list is full. The number of points on the 
global polygon list exceeds 256. The points which exceed 
256 are ignored. This error can be corrected by inserting a 
call to polygon (which clears the global polygon list by 
displaying its contents) before die call to 
partial_polygon which caused the overflow. 

Arc points do not lie on circle. The starting and ending 
points of either an open or close circular arc do not lie on 
the perimeter of the circle described by the arguments cl 
and rad . If this error occurs, the arc is not drawn. Correc¬ 
tive action may include determination of the endpoints 
with die application program (for example c2.x =* 
rad*cos(start_angle);). 

Arc points do not lie on ellipse . The starting and ending 
points of either an open or close elliptical arc do not lie on 
die perimeter of the ellipse described by the arguments cl, 
c2 , and c3 . If this error occurs, the arc is not drawn. 
Corrective action may include determination of the end¬ 
points with die application program (see error 11). 

Cell array dimensions dx/iy are too small . The dimen¬ 
sions of the cell array are too small for a cell array element 
to be mapped onto one pixel of the view surface. The cell 
array is not drawn. This error depends on the physical size 
of the view surface as well as the limits of VDC space. 
Therefore, corrective action might require changing the 
size of the view surface, VDC space, or both. 

Cell array dimensions must be positive . Negative cell 
array dimensions are not permitted. Corrective action 
requires changing the parameters m the cell array func- 
doiL 

Is not used. 

Value outside cfview surface . A coordinate of a pixel 
array is outside the physical range of die view surface. 

The pixel array is not drawa Change die arguments to the 
pixel_array orbitblt__source__array 

Pixrect not created. One of the BitBlt functions required 
a user-defined pixrect , and that pixrect had not been 
created. Corrective action involves creating a pixrect in 
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D.7, Input (80-97) 



Q 


EINDNOEX [80] 


EINDINIT [81] 


EINDALIN [82] 


EINASAEX [83] 


EINAIIMP [84] 


EINNTASD [85] 


EINTRNEX [86] 


EINNECHO [87] 

EINECHON [88] 


your application program before calling the offending 
BitBlt i^cdon. 

device does not exist . The input device specification 
(specified by the devclass and devnum ailments of most 
input functions) does not exist Corrective action involves 
resetting the device specification to a valid device. 

Input device not initialized . A call to an input device 
function specified a device which was not initialized. 

Calls which generate this error have no effect A call to 
initiali 2 e_input_device should be inserted 
before the call generating the error. 

Input device already initialized . An attempt to initialize a 
device which has previously been initialized. The parame¬ 
ters to tire offending call to 

initialize_input_device are ignored. Removing 
the offending call to initialize_input_device 
will correct this error. 

Association already exists . An attempt is being made to 
bind the input device to a trigger to which it has been pre¬ 
viously boimd. The status of the input device trigger are 
unchanged. This error is purely informational and no 
corrective action is required. 

Association is impossible . An attempt is being made to 
bind die input device to a trigger to which it cannot be 
bound. For example a IC_STRING device cannot be 
bound to a mouse button. To eliminate this error, change 
the arguments to the offending call of the as sociat e 
function. 

Association does not exist . An attempt to set-up call an 
input function which specifies a device with no associated 
triggers was made. The offending call is ignored. Correc¬ 
tive action involves calling associate before the 
offending call is issued. 

Trigger does not exist . An attempt was made to associate 
or inquire about a trigger whidi has a number less than one 
or greater dian five. The offending call is ignored. To 
eliminate the enor, change the trigger number. 

Input device does not echo. CHOICE devices do not sup¬ 
port echo. Corrective action requires removing the call to 
echo_on from the api^cation {»ogram. 

Echo already on . A call to echo_on has been made to a 
device whose echoing ability has already been activated. 
To stop generation of the error eitiier remove the offending 
call or diange the arguments to specify a device whose 
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EINEINCP [89] 

EINERVWS [90] 

EINETNSU [91] 

EINENOTO [92] 

EIAEVNEN [93] 

EINEVNEN [94] 

EBADDATA [95] 

ESTRSI2E [96] 

EINQOVFL [97] 


echo is currently off. 

Echo incompatible with existing echos . Although 
SunCGI can support certain combinations of echos (such 
as IC_STRING and ICJLOCATOR), not all combinations 
are supported. The easiest remedy is to remove the most 
recent call to echo_^on from the application program. 

Echoregion larger tiuin view surface . Error 91 is gen¬ 
erated when the rei^gle defined by the echoregion argu¬ 
ment exceeds die limits of VDC space. To eliminate this 
error, change the values to the echoregion argument to be 
within the confines of VDC space. 

Echo type not supported. All devices except the 
IC_STROKE device only support one type of echo. 
Tterefore, assigning a value to echotype other than zero or 
one will produce an error for any device except 
IC_STROKE. Corrective action involves changing the 
value of the echotype argument. 

Echo not on. The device echoing has not been turned on. 
Either remove the call to echo_of f, turn the echo on, or 
change the device specification. 

Events already enabled. Events have already been 
enabled for the specified device. The solution is to remove 
the offending call to enable_events. 

Events not enabled. Events have not been enabled for die 
specified device. The solution is to include a call to 
enable_events before a call to the await_event, 
sample__event, or request_event function is made 
with die specified device as input parameter. 

Contents of input data record are invalid. The value 
argument of initial! ze_lid function is out of range 
or is the wrong type. The solution is to change the con¬ 
tents value argument 

Length of initial string is greater than the implementation 
defined maximum. The initial string in the value argument 
is greater than 80 characters. Shorten the string. 

Input queue has overflowed. The event queue can no 
longer record input events. Solutions include flushing the 
evera queue or ctequeueing events with the 
await^event, sainple_event, or 
request_event function. 
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D.8. Implementation EMEMSPAC [110] 

Dependent (110-112) 

ENOTCSTD [111] 
ENOTCCPW [112] 


Space allocation has failed. A function which was sup¬ 
posed to work has failed. The only action which you can 
take is to eliminate other processes which may be using 
memory. If you have eliminated all otl^r processes, and 
this error is still generated, please contact SUN Microsys¬ 
tems. 

Function or argument not compatible with standard CGI. 
A function call is not supported by the CGI library. 

Function or argument not compatible with CGIPW mode . 
A function call is not supported by the cgipw library. 


D.9. Possible Causes of Visual 
Errors 


Table D-1 Possible Causes of Visual Errors 


Behavior 

Possible Cause 

Segmentation fault for 
open_vws 

devdd argument for open_vws 
is declared as a pointer (the 
address of devdd should be 
passed). 

No primitives displayed 

View surface not initialized. 

View surface not active. 

VDC to device coordinate map¬ 
ping makes objects too small. 
Dipping rectangle is too small 
and clipping is ON. 

Perimeter visibility is set to 

OFF and interior style is set to 
HOLLOW. 

line colo . or fill colo . is set to 
background color. 

Primitives displayed on 
undesired view surfaces 

Undesired view surfaces have 
not been deactivated. 

Segmentation fault for inquiry 
functions 

passing variable instead of 
address (&) of variable. 
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Table D-2 Primitive'Specific Errors 


Behavior 

Possible Cause 

Polylines or polymarkers aren’t 
displayed. 

Width or size is zero. 

Color is the same as back¬ 
ground. 

Polygon borders aren’t 
displayed. 

Width is zero. 

Color is die same as back¬ 
ground. 

Perimeter visibility is set to 

OFF. 

Circles aren’t displayed. 

Width or size is zero. 

Color is the same as back¬ 
ground. 

Ellipses aren’t displayed. 

Widdi or size is zero. 

Color is the same as back¬ 
ground. 

Text isn’t displayed. 

Width or size is zero. 

Color is the same as back¬ 
ground. 

character height is too small, 
coordinates are outside the 


range of VDC space or the clip¬ 
ping rectangle. 

Cell arrays aren’t displayed. 

dx or dy arguments arc too 
small. 

Color is the same as back¬ 
ground. 

Cell arrays aren’t displayed on 

Mapping from cell size to view 

all active view surfaces. 

surface for smaller view sur¬ 
faces is too small. 

Pixel arrays aren’t displayed. 

Location is outside of view sur¬ 
face or clipping rectangle. 

Color is the same as back¬ 
ground. 

BitBlts aren’t displayed. 

Width or size is zero. 

Color is the same as back¬ 
ground. 
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Q 

Table D-3 Attribute Errors 


Behavior 

Possible Cause 

Attribute setting has no effect 

attribute ASF is set to BUN¬ 
DLED. 

Text attributes have no effect 

text precision is set to CHAR¬ 
ACTER, 

attribute ASF is set to BUN¬ 
DLED. 

PATTERN fill is the same as 
HATCH 

pattern index, and hatch index 
are identical 

pattern size. is too small 

PATTERN fill is different on 
different view surfaces. 

View surfaces are of different 
size. 


Table D-4 Input-specific Errors 


Behavior 

Possible Cause 

Input device does not report 

device not initialized 

Input device does not echo 

echo not initialized 

Input device does not echo on 

echo region not set to whole 

whole view surface 

view surface. 
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Sample Programs 


E.l. Martini Glass 


The following program draws a martmi glass. The program exits after 10 
seconds. 
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#include <cgidefs.h> 

Ccoorlist martinilist; 

Ccoor glass_coords[10] = { 0,0, 

- 10 , 0 , 

-l.if 

- 1 . 20 , 

“15,35, 

15,35, 

1 , 20 , 

1 . 1 . 

10 , 0 , 

0,0 ); 

Ccoor water_coords [2] =* { -12,33, 

12,33 }; 

Ccoor vpll = { -50,-10 ); 

Ccoor vpur = { 50,80 }; 

main() 

{ 

Cvwsurf device; 

Cint name; 


NORMAL_VWSURF < device, PIXWINDD); 
open_cgi(>; 

open_vws<&name, &device); 
vdc extent(&vpll, &vpur); 


martinilist.ptlist * glass_coords; 
martinilist.n = 10; 
polyline<Smartinilist); 
martinilist.ptlist = water_cootds; 
martinilist.n = 2; 
polyline(Smartinilist); 

sleep (10); 
close_vws(name); 
clo3e_cgi(); 


E.2. Tracking Box 


Figure E-1 Martini Glass Example Program 

The following program demonstrates the use of the CGI input functions. A 
square is displayed on die screen and moved with the mouse. The program exits 
if the mouse is still for five seconds. 
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#include <cgidefs.h> 

#define DEVNUM 1 /* device number */ 

♦define MOUSE_POSITION 5 /* trigger number */ 

♦define TIMEOUT (5 * 1000 * 1000) /* timeout in microseconds */ 

Ccoor ulc * {1000/ 2000}; 

Ccoor Ire = {2000/ 1000}; 

main() 

{ 

Cint name; 

Cvwsurf device; 

Cawresult stat; 

Cinrep sample; /* device measure value */ 

Ccoor samp; /* LOCATOR'S X/y position */ 

Cint trigger; /* trigger number */ 

NOEMAL_VWSURF{device/ PIXWINDD); 
sample.xypt = &samp; 
samp .X = 0; 
samp.y =27000; 

open_cgi(); 

open_vws(&name/ Sdevice); 
set_global_drawing_mode(XOR); 
initialize_lid{IC_LOCATOR/ DEVNUM/ &sample); 
associate(MOUSE_POSITION/ IC_LOCATOR, DEVNUM); 
rectangle<&Ire, &ulc); /* draw first rectangle */ 

/* wait TIMEOUT micro-seconds for input and chec)c the status */ 
while (reque3t_input(IC_LOCATOR/ DEVNUM, TIMEOUT, 

fistat, fisample, fitrigger), (stat == VALID_DATA)) { 

if ((sample.xypt-*>x !» ulc.x) || (sample-xypt->y !- Irc.y) ) { 
rectangle(&lrc/ &ulc); 

Irc.y = sample.xypt->y; /* move to new location */ 

Irc.x = (sample.xypt->x + 1000); 
ulc.x = sample.xypt->x; 
ulc.y = (sample.xypt->y + 1000); 
rectangle(&lrc, Sulc); 

} 

} 

dissociate (MOUSE_POSITION, IC__LOCATOR/ DEVNUM); 
release_input_device(IC_LOCATOR/ DEVNUM); 
clos6_vws(name); 
close_cgi() ; 

} 

^. 


Figure E-2 Tracking Box Example Program 
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F.l. cgipw Functions 
Open Pixwin CGI 

Open a CGI Pixwin 



Using SunCGI and Pixwins 


The CGI standard does not provide facilities for dealing with multiple overlap¬ 
ping windows. An application program can use SunCGI and Pixwins features 
through the cgipw functions. These functions combine the richness of CGI’s 
primitives with the ability of Pixwins to manage multiple (potentially overlap¬ 
ping) windows. 

This appendix assumes familiarity with both SunCGI and Pixwins. See Sun- 
View Programmer's Guide for more information on Pixwins. An example pro¬ 
gram is included at the end of this appendix in Figure F-L 

If you decide to use CGI and Pixwins, you may not use the standard SunCGI 
calls. Instead you must use cgipw calls. For example, cgipw_polyline 
replaces polyline. The first argument of each cgipw ^ncdon is a pixwin 
descriptor of type Ccgiwin. The file <cgipw. h> must be included in the 
cgipw application program instead of <cgidef s. h>. 

The four functions open_pw_cgi, open_cgi_pw, close_cgi_pw and 
closejpw_cgi are necessary for managing the SunCGI - Pixwins interface. 

Cerror open_pw_cgiO 

open_pw_cgi initializes CGI by setting the attributes to the default values and 
setting the VDC to device coordinate mapping to 1:1. Therefore, all input and 
output primitives will use device coordinates. The origin of the device coordi¬ 
nates is in the upper left-hand comer instead of the lower left-hand comer. The 
entire window is used, not just a square region within it No standard errors are 
specified for open_pw__cgi. If open_j>w_cgi returns a nonzero result, then 
the initialization failed. open_pw_cgi corresponds to open cgi. 

Cerror open_cgi_pw(pw, desc, name) 
struct pixwin *pw; /* pixwin */ 

Ccgiwin *desc; /* CGI pixwin descriptor */ 

Cint *name; 

open_cgi_pw informs CGI of the jxxwin pointed to by ^. Calls to CGI primi¬ 
tives may then reference this pixwirt However, CGI does not guarantee that a 
pixwin exists or is in any other way properly initialized, desc is a pointer to a 
CGI pixwin descriptor allocated by the application program and defined by 
open_cgi_pw. It will be used as the first argument to cgipw functions. Calls 




143 


VcisioD C of 17 March 1986 







144 SunCGI Reference Manual 


Errors 


Close a CGI Pixwin 


Errors 


Close Pixwin CGI 


Errors 


FJ2. Using cgipw 


may also be made to any pixwin function (see example program). Multiple calls 
to open_cgi_pw with pointers to different Ccgiwin structures will allow 
primitives to be displayed on multiple view surfaces by repeating calls to cgipw 
functions with different Ccgiwin descriptors. Attributes are local to the pixwin 
associated with the CGI descriptor passed to the cgipw attribute functions. 
open_cgi_pw corresponds to open^vws. open__pw__cgi must be called 
prior to open_cgi_pw; otherwise, error 111 is returned. Odier errors (as with 
open_vws may also be detected. 


ENOTOPOP [5] 

ENOWSTYP [11] 
EMAXVSOP [12] 
EMEMSPAC [110] 


CGI not in proper state CGI shall be either in state CGOP, 
VSOP.orVSAC. 

Specified view surface type does not exist 
Ma ximum number of view surfaces already open. 

Space allocation has failed. 


Cerror close_cgi_pw(desc) 

Ccgiwin *desc; /* CGI pixwin descriptor */ 

close_cgi_pw takes the CGI pixwin descriptor desc as an argument and 
removes it from the list of pixwins that CGI writes to. The pixwin is not closed. 
close_cgi_pw corresponds to close_vws, and may return any of the errors 
close_vws detects (except 112). 

ENOTOPOP [5] CGI not in proper state CGI shall be either in state CGOP, 
VSOP, orVSAC. 

EVSIDINV [10] Specified view surface name is invalid. 

EVSNOTOP [13] Specified view surface not open. 


Cerror clo3e_pw_cgi() 

close_pw_cgi takes care of leaving CGI in an orderly state. This function 
should be called before exiting the application program. close_pw_cgi 
corresponds to dose^cgi. 

ENOTOPOP [5] CGI not in proper state CGI should be in state CGOP, 
VSOP,orVSAC. 

After calling the two initialization functions (open_pw_cgi and 
open_cgi_pw) the application program may call functions from both the 
Pixwins and cgipw libcaiies. Hgure F>1 contains an example program that uses 
cgipw functions. 

Since cgipw ftmctions use a 1:1 mapping from VDC ro device coordinates, attri¬ 
butes in VDC units (such as pattern size and character height) will be huge 
unless they are reset. And because the cgipw origin is the device coordinate 
origin, tl» upper left-hand comer, attributes with direction or position (e.g., pat¬ 
tern r^erence point and character orientation ) have their meaning reversed in 
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they dimension. 

Most cgipw functions do not print error messages even if the error warning 
mask is INTERRUPT or POLL. They all return error codes which may be tested. 
The application program should not use both SunCGI and window system input 
functions, since both SunCGI and the window system share a common event 
queue. For example, events handled by a SunCGI function will not be handled 
by a window system call after the SunCGI call. 

A list of the cgipw fimetions and their corresponding SunCGI functions is 
given in Table F-1 below. If a function is not included in this table, then use the 
nonnal SunCGI function except as described below in Table F-2. Most of the 
functions listed below are output and attribute functions; however, the tracking 
functions are listed so that you can control which surfaces input devices echo on. 
The arguments of the cgipw functions are die same as those of the SunCGI 
functions except diat the first argument is always a desc argument of type 
Ccgiwin. desc is a pointer to a pixwin descriptor filled in by the 
open_cgi_j>w function. 

F.3. cgipw Functions Table F-1 contains a list of functions available in cgipw mode. SunCGI func¬ 

tions incompatible with cgipw mode are given in Table F-2. 
partial_polygon may be used with cgipw_polygon, but the global 
polygon list is fwd after use by cgipw_polygon, so calls to 
partial_polygon must be repeated prior to use of cgipw_polygon on 
another view surface. 


Table F-1 List of Functions 


SunCGI Function Name 

cgipw Function Name 

append_text(flag, tstring} 

egipw^append^text(desc, flag, tstring) 

cell_array(p, q, r, dx, dy, colorind) 

cgipw_cell_array(desc, p, q, r, dx, dy, colorind) 

character__expansion_factor (sfac) 

cgipw_charaotar_expan8ion__factor (desc, sfac) 

character_height(height) 

cgipw_character_^height (desc, height) 

character_orientation(xup, yup, xbaae, 

cgipw_chaxacter_orientation(desc, xup, yup, xbase, 

ybase) 

ybase) 

character_path(path) 

cgipw__charactex^j}ath (desc, path) 

character_set_index(index) 

cgipvr^character__eet_index (desc, index) 

character_8pacing(speratio) 

cgipw_charactex_spacing(desc, speratio) 

circle(cl, rad) 

cgipw_circle(desc, cl, rad) 

circular_arc_3pt (cl, c2, c3) 

egipw_circular_arc_3pt(desc, cl, c2, c3) 

circular_arc_3pt_close(cl, c2, c3. 

cgipw_^circular_^are_3pt_close (dose, cl, c2, c3. 

close) 

close) 

cixcular_arc_center(cl, c2x, c2y, c3x. 

cgipw__cixcular__arc_center(desc, cl, c2x, c2y, c3x, 

c3y, rad) 

c3y, rad) 

circular_arc_c«nter_close(cl, c2x, 

cgipw_eircular_arc_center_clo8e(de8c, el, c2x. 

c2y, c3x, c3y, rad, close) 

c2y, c3x, c3y, rad, close) 

color__table (istart, clist) 

cgipw_colox_table(desc, istart, clist) 

define_bundle^index(index) 

cgipw_^define_bundle_index (desc, index) 

disjoint_polyline(polycoors) 

egipw_di8joint_polyline(desc, polycoors) 

ellipse(cl, majx, miny) 

cgipw_elllpse(desc, cl, majx, miny) 
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Table F-1 List of c gipw Functions — Continued 


SunCGl Function Name 


cgipw Function Name 


elliptical_arc(cl, sx, sy, ex, ey, 
majx, miny) 

elliptical_arc_close (cl, sx, ay, ex, 
ey, majx, miny, close) 
fill_area_bundle_index(index) 
fill_color(color) 
fixed_font(index) 
hatch_index(index) 
inquire_aspect_aource_flags() 
inquir6_drawing_mode(visibility, 
source, destination, combination) 
inquire_fill_area_attributes() 
inquire__line_attributefe () 
inquire_marker_attributes() 
inquire_pattern_attributes() 
inquire__pixel_array (p, m, n, colorind) 
inquire_text_attribute3{) 
inquire_text_extent(tstring, nextchar, 
concat, lleft, uleft, uright) 
interior_style(istyle, perimvis) 
line_oolor(index) 
line_endstyle(ttyp) 
line_type(ttyp) 
line_width(index) 

line_vfidth_8pecification_mode (mode) 
marker_color(index) 
roarker_aize(index) 

marker_size_specification_mode(mode) 
marker_type(ttyp) 
pattern_index(index) 
pattern_reference_point(open) 
pattern_size(dx, dy) 
perimeter_color(index) 
perimeter_type(ttyp) 
perimeter_width(width) 
perimeter_width_8pecif ication_mode(roode) 

pixel_array(pcell, m, n, colorind) 
polygon(polycoors) 
polyline(polycoors) 
polyline_bundle_index(index) 
polymarker(polycoors) 
polymarker_bundle_lndex(index) 
rectangle(Ire, ulc) 
set_a3pect_sourc6_flags(flags) 
text(cl, tstring) 


cgipw_elliptical_arc(desc, cl, ax, ay, ex, ey, 
majx, miny) 

egipw_elliptical_arc_close(desc, cl, sx, sy, ex, 
ey, majx, miny, close) 

cgipw_fill_area_bundle_index(desc, index) 
cgipw_fill_color(desc, color) 
cgipw_£ixed_£ont(desc, index) 
cgipw_hatch_index(desc, index); 
cgipw_inquire_aapect_aource_flaga (desc) ; 
cgipw_inquire^drawing_mode(desc, visibility, 
source, destination, combination) 
cgipw_inquire_fill_area_attributea(desc); 
cgipw_inquire_line_attributes(desc); 
cgipw_inquire_marker_attributes(desc); 
cgipw_inquiro_pattern_attribute8(desc); 
cgipw_inquire__pixel_array (desc, p, m, n, colorind) 
cgipw_inquire_text_attributes(desc); 
cgipw__inquire_text_extent (desc, tstring, nextchar, 
concat, lleft, uleft, uright) 
cgipw_interior_atyle(desc, istyle, perimvis) 
cgipw_line_color(desc, index) 
cgipw_line_endstyle(desc, ttyp) 
cgipw_line_type(desc, ttyp) 
cgipw_line_width(desc, index) 

cgipw_line_width_speci£ication_mod6(desc, mode) 
cgipw_marker_color(desc, index) 
cgipw_marker_8ize(desc, index) 

cgipw_marker_^aize_specification_mode (desc, mode) 
cgipw_marker_type(deac, ttyp) 
cgipw_pattern_index(desc, index); 
cgipw_pattern_re£erence_point(desc, open) 
cgipw_pattern_aize(desc, dx, dy) 
ogipw_perimetor_color(desc, index) 
cgipw perimetertvpe(desc, ttyp) 
cgipw^_perimeter_wldth (desc, width} 
cglpw^j>erimeter_width_speci£ication_mode (desc, 
mode) 

cglpw_pixel_array(desc, pcell, m, n, colorind) 
cgipw_polygon(desc, polycoors) 
cgipw_polyllne(desc, polycoors) 
cgipw_polyline_bundle__index (desc, index) 
cglpw^polymarker(desc, polycoors) 
cgipw_polymarker_bundle_Index(desc, index) 
cgipw^rectangle(desc. Ire, ulc) 
cgipw_set_aspect_ 80 uroe_£lags(desc, flags) 
cgipw_text(desc, cl, tstring) 
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Table F-1 List of c gipw Functions — Continued 


SunCGI Function Name 

cgipw Function Name 

text_alignment(halign, valign, 

cgipw_text_alignment(desc, halign, valign. 

hcalind, vcalind) 

hcalind, vcalind) 

text_bundle_indQX(index) 

cgipw_toxt_bundle_index(de sc, index) 

text_color(index) 

cgipw_text_color(desc, index) 

text_font_index(index) 

cglpw_text_font_index(desc, index) 

text_precision(ttyp) 

cgipw_text_precision (desc, ttyp) 

vdm_text(cl, flag, tstring) 

cglpw_vdin_text (desc, cl, flag, tstring) 


Table F-2 SunCGI Functions not Compatible with cgipw Mode 


Function 

Discussion 

clear_control 

All clear extents are identical 

clip_indicator 

whenc^g is 
CLIP_RECTANGLE 

clip_rectangle 

Instead, use pw_region 
prior ro open_cgi_pw 

close_cgi 

Use close_pw_cgi 

close_vws 

Use close_cgi^w 

device_viewport 

use pw_region prior to 
open_cgi_pw 

open_cgi 

Use open_pw_cgi 

open_vws 

Use open_cgi_pw 

partial_polygon 

global polygon list is freed 
after cgipw_polygon 

vdc extent 

cgipw’s VDC space is identi¬ 
cal to screen space 


F.4. Example Program Figure F-1 contains an example program that uses cgipw functions. This exam¬ 

ple uses retained pixwins to ease redisplay after window obstruction (see Section 
2,3). This makes the program slower during image generation, because it writes 
both on the screen and onto a copy retained in memory. 
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#include <cgipw.h> 

♦include <suntool/gfxsw.h> 

struct pixwin *inypw; 
struct gfxsubwindow *mine; 

main {) 

Ccgiwin vpw; 

Ccoor bottom; 

Ccoor top; 
int name; 
int op; 

mine >= gfxsw_init (0, 0) ; 
gfxsw_getretained(mine); 
mypw = mine->gfx_pixwin; 
pw_writebaclcground(mypw, 0, 0, 

mypw->pw__prretained->pr_size .x, 
mypw->pw_prretained->pr_size.y, PIX_CLR); 

open_pw_cgi(); 

open_cgi_pw(mypw, &vpw, finame); 
op == PIX_COLOR(1) 1 PIX_SRC; 

pw_write(mypw, 0, 0, 100, 100, op, 0, 0, 0); 

bottom.X = 300; 

bottom.y = 100; 

top.x » 200; 

top.y = 0; 

cgipw_interior_style(&vpw, SOLIDI, ON); 
cgipw_rectangle(&vpw, fibottom, Stop); 
sleep (10); 

close_cgijpw(&vpw); 
close_pw_cgi () ; 


Figure F-1 Example cgipw Program 
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Using SunCGI with Fortran Programs 


All functions provided in SunCGI may be called from FORTRAN programs by 
linking them widi the libcgi77. a library. This is done by using the/?? com¬ 
piler Nvith a command line like; 

-, 

% f77 -o box box.f •-lcgi77 -Icgi -Isunwindow -Ipixrect -Im 
_/ 



where box. f is the FORTRAN source program. Note that libcgi. a must be 
linked with the program (the -Icgi option), and iibcgi77 . a must precede it 
(the -lcgi77 option). 

Defined constants may be referenced in source programs by including 
cgidef s77 . h. In a FORTRAN program, this must be done via a source state¬ 
ment like: 

include 'cgidefs77.h' 

This include statement must be in eac^ FORTRAN program unit which uses the 
defined constants, not just once in each source program file. 

In the Sun release of FORTRAN, names are restricted to sixteen characters in 
length and may not contain the underiine character. For this reason, FORTRAN 
programs must use abbreviated names to call the corresponding SunCGI func¬ 
tions. The correspondence between the lull SunCGI names and the FORTRAN 
names appears later in diis appendix. In addition, FORTRAN declarations for all 
SunCGI functions appear at the end of this appendix. 


G.l. Programming Tips 


w 


• The abbreviated names of the SunCGI functions are less readable dian the full 
length names because the imderline character cannot be used in the FORTRAN 
names. However, since FORTRAN doesn’t distinguish between upper-case and 
lower-case letters in names, upper-case characters can be used to improve rea¬ 
dability. There is an example of this later in this appendix. 

• Character strings passed from FORTRAN programs to SunCGI cannot be 
longer dian 256 characters. 

• Pointers returned by C fimctions are handled in FORTRAN as integer*4 
values, and exist solely to be passed to other Sun graphics functions. 

• FORTRAN passes ail arguments by reference. Although some SunCGI func¬ 
tions receive arguments by value, the FORTRAN programmer need not worry 
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about this. The interface routines in /usr/lib/libcgi77 . a handle this 
situation correctly. When in doubt, look at the FORTRAN declarations for 
SunCGI functions at the end of this appendix. 

• Some SunCGI functions have structures as arguments or return values. These 
are handled in FORTRAN by unbundling the structures into separate arguments. 
In general, these will be in the same order, and have the same names, as the 
membeia of the C structures. One exception is die Ccoorlist structure, 
which is replaced in FORTRAN with an array of x’s, and one of y’s, rather than 
an array of x-y pairs. You may need to consult both the C and FORTRAN docu¬ 
mentation to detennii^ which FORTRAN arguments are input values, and which 
are output 

• Since FORTRAN does not distinguish between upper-case letters and lower-case 
letters in identifiers, any FORTRAN program unit which includes the 
cgidef s 7 7. h header file cannot use the same spelling as any constant 
defined in that header file, regardless of case. 

• The function cfqoutcap returns the FORTRAN binding names of the output 
capabilities, rather than the C bindings. This is an exception to the rule that 
the FORTRAN library provides a transparent interface to the C functions. 

G.2. Example Program This example is the FORTRAN equivalent of the very simple program for drawing 

a martini glass. 
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program test 
parameter (ibignum=256) 
integer name 

character screenname* (ibignum) 

integer screenlen 

character windowname* (ibignum) 

integer windowlen 

integer windowfd 

integer retained 

integer dd 

integer cmapsize 

character cmapname* (ibignum) 

integer cmaplen 

integer flags 

character ptr* (ibignum) 

integer noargs 

c coordinates of glass 

integer xc(10),yc(10),n 

c coordinates of waterline, 

integer xc2(2)/yc2(2) 
data xc /O,-10,-1,-1,-15,15,1,1, 10, 0 / 
data yc /O,0,1,20,35,35,20,1,0,0 / 
data xc2 /-12,12/ 
data yc2 /33,33/ 


c open cgi 

call cfopencgiO 
c open a pixwin 

dd = 4 

call cfopenvws(name,screenname,screenlen,windowname, 

+ windowlen,windowfd,retained,dd,cmapsize, 

+ cmapname,cmaplen,flags,ptr,noargs) 
c reset VDC space 

call cfvdcext(-50,-10,50,80) 
c draw martini glass and waterline 

n - 10 

call cfpolyline(xc,yc,n) 
n - 2 

call cfpolyline(xc2,yc2,n) 
c sleep for 10 seconds 

call sleep(10) 
c close and exit 

call cfclosecgiO 
call exitO 
end 

V____ _^ 


Figure G-1 Example FORTRAN Program 

ICfMyitsm* 
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G.3. FORTRAN Interfaces to 
SunCGI 


Note: Although all SunCGI procedures are declared here as functions, each may 
also be called as a subroutine if the user does not want to check the returned 
value. 


Table G-1 SunCGI Fortran Binding — Part I 


CGI Specification Name \ _ 

Activate View Surface integer 

(SunCGI Extension) integer 


_ Fortran Binding 

function cfactvws(name) 
name 


Append Text integer function cfaptext (flag, string) 

integer flag 
character*(*) string 


Associate integer function cf assoc (trigger, devclass, devnum) 

integer trigger 
integer devclass 
integer devntm 

Await Event integer function cf await ev (timeout, valid, devclass, 

1 devnum, x, y, xlist, ylist, n, val, choice, string, 

2 segid, pickid, message_link, replost, time_stamp, 

3 qstat, overflow) 
integer timeout 
integer valid 
integer devclass 
integer devnum 
integer x, y 
integer xlist(*) 
integer ylist(*) 
integer n 

real val 
integer choice 
character*(*) string 
integer segid 
integer pickid 
integer message_link 
integer replost 
integer time_stamp 
integer qstat 
integer overflow 
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Table G-1 SunCGI Fortran Binding - Part 1 — Continued 


CGI Specification Name 

Fortran Binding 

BitBlt Pattern Array 

integer function cfbtblpatarr(pixpat, px, py, pixtarget, 

1 rx, ry, ox, oy, dx, dy, name) 

integer pixpat 

integer px, py 

integer pixtarget 

integer rx, ry 

integer ox, oy 

integer dx, dy 

integer name 

BitBlt Patterned Source 

integer function cfbtblpatsouarr(pixpat, px, py, pixsotirce. 

Array 

1 sx, sy, pixtarget, rx, ry, ox, oy, dx, dy, name) 

integer pixpat 

integer px, py 

integer pixsource 

integer sx, sy 

integer pixtarget 

integer rx, ry 

integer ox, oy 

integer dx, dy 

integer name 

BitBlt Source Array 

integer function cfbtblsouarr(bitsource, xo, yo, xe, ye, 

1 bit target, xt, yt, name) 

integer*4 bitsource, bittarget 
integer xo, yo, xe, ye, xt, yt 
integer name 

Cell Array 

integer function cfcellarr(px, qx, rx, py, qy, ry, 

1 dx, dy, colorind) 

integer px, py 
integer qx, qy 
integer rx, ry 
integer dx, dy 
integer colorind(*) 

Character Expansion 

integer function cfcharexpfac(efac) 

Factor 

real efac 

Character Height 

integer function efeharheight(height) 
integer height 

Character Orientation 

integer function cfcharorientfbx, by, dx, dy) 
real bx, by, dx, dy 

Character Path 

integer function cfcharpath(path) 
integer path 

Character Set Index 

integer function cfcharsetix(index) 
integer index 
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Tabl e G-1 SunCGI Fortran Binding - Part I — Continued 




CGI Specification Name 

Fortran Binding 

Character Spacing 

integer function cfcharspacing(efac) 
real efac 

Circle 

integer function cfcircle(x, y, rad) 
integer x 
integer y 
integer rad 

Circular Arc 3pt Close 

integer function cfcircarcthreecl(clx, cly, c2x, c2y, 

1 c3x, c3y, close) 

integer clx, cly, c2x, c2y, c3x, c3y 

integer close 

Circular Arc 3pt 

integer function cfcircarcthree(clx, cly, c2x, c2y, 

1 c3x, c3y) 

integer clx, cly, c2x, c2y, c3x, c3y 

Circular Arc Center 

Close 

integer function cfcircarccentcl(clx, cly, c2x, c2y, 

1 c3x, c3y, rad, close) 

integer clx, cly, c2x, c2y, c3x, c3y 
integer rad 
integer close 

Circular Arc Center 

integer function cfcircarccent(clx, cly, c2x, c2y, c3x, m 

1 c3y, rad) ^ 

integer clx, cly, c2x, c2y, c3x, c3y 
integer rad 

Clear Control 

integer function cfclrcont(soft, hard, intern, extent) 
integer soft, hard 
integer intern 
integer extent 

Clear View Surface 

integer function cfclrvws(name, defflag, color) 
integer name 
integer defflag 
integer color 

Clip Indicator 

integer function cfclipind(flag) 
integer flag 

Clip Rectangle 

integer function cfcliprect(xmin, xmax, ymin, ymax) 
integer xmin, xmax, ymin, ymax 

Close CGI 
(SunCGI Extension) 

integer function cfclosecgiO 

Close View Surface 
(SunCGI Extension) 

integer function cfclosevws(name) 
integer name 


c 
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Table G-2 SunCGI Fortran Binding - Part II 


CGI Specification Name 


Color Table 


Deactivate View Surface 
(SunCGI Extension) 

Define Bundle Index 
(SunCGI Extension) 


Device Viewport 


Disable Events 


Disjoint Polyline 


Fortran BintUng 


integer function cfcotable(istart, ra, ga, ba, n) 

integer istart 

integer ra(*), ga(*), ba(*) 

integer n 

integer function cfdeactvws(name) 
integer name 

integer function cfdefbundix(index, linetype, linewidth, 

1 linecolor, marktype, marksize, markcolor, intstyle, 

2 batchindex, pattindex, fillcolor, perimtype, 

3 perimwidth, perimcolor, tSextfont, textprec, 

4 charexpand, charspace, textcolor) 

integer index 

integer linetype 
real linewidth 
integer linecolor 
integer marktype 
real marksize 
integer markcolor 
integer intstyle 
integer batchindex 
integer pattindex 
integer fillcolor 
integer perimtype 
real perimwidth 
integer perimcolor 
integer tSextfont 
integer textprec 
real charexpand 
real charspace 
integer textcolor 

integer function cfdevvpt(name, xbot, ybot, xtop, ytop) 
integer name 

integer xbot, ybot, xtop, ytop 

integer function cfdaevents(devclass, devnum) 
integer devclass 
integer devnum 

integer function cfdpolyline(xcoors, ycoors, n) 
integer xcoors(*) 
integer ycoors(*) 
integer n 
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Table G-2 SunCGI Fortran Binding — Part II — Continued 


CGI Specification Name 
Dissociate 


Ellipse 


Elliptical Arc Close 


Elliptical Arc 


Enable Events 

Fill Area Bundle Index 

Fill Color 

Fixed Font 
(SunCGI Extension) 

Flush Event Queue 


Fortran Binding 

integer function cfdissoc(trigger, devclass, devnum) 
integer trigger 
integer devclass 
integer devnxim 

integer function cfellipse(x, y, majx, miny) 
integer x, y 
integer majx, miny 

integer function cfelliparccl(x, y, sx, sy, ex, ey, 

1 majx, miny, close) 
integer x, y 
integer sx, sy 
integer ex, ey 
integer majx, miny 
integer close 

integer function cfelliparc(x, y, sx, sy, ex, ey, majx, 

1 miny) 

integer x, y 

integer sx, sy 

integer ex, ey 

integer majx, miny 

integer function cfenevents(devclass, devnum) 
integer devclass 
integer devnum 

integer function cfflareabundix(index) 
integer index 

integer function cfflcolor(color) 
integer color 

integer function cffixedfont(index) 
integer index 

integer function cfflusheventqu() 
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Table G-2 SunCGI Fortran Binding - Part II — Continued 


CGI Specification Name 
Get Last Requested 
Input 


Hard Reset 
Hatch Index 


Initialize UD 


Initiate Request 


Inquire Aspect Source 
Flags 


Fortran Binding 


integer function cfgetlastreqinp (devclass, devnuiti, valid, 

1 X, y, xlist, ylist, n, val, choice, string, segid, 

2 pickid) 
integer devclass 
integer devnum 
integer valid 
integer x, y 
integer xlist(*) 
integer ylist(*) 
integer n 

real val 
integer choice 
character*(*) string 
integer segid 
integer pickid 

integer function cfhardrst() 

integer function cfhatchix(index) 
integer index 

integer function cfinitlid(devclass, devnum, x, y, xlist, 

1 ylist, n, val, choice, string, segid, pickid) 

integer devclass 

integer devnum 

integer x, y 

integer xlist(*) 

integer ylist(*) 

integer n 

real val 

integer choice 

character*(*) string 

integer segid 

integer pickid 

integer function cfinitreq(devclass, devnum) 
integer devclass 
integer devnum 

integer function cfqasfs(n, num, vals) 
integer n 
integer num(*) 
integer vals(*) 
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Table G-2 SunCGI Fortran Binding - Part //— Continued 


CGI Specification Name 
Inquire BitBlt 
Alignments 


Inquire Cell Array 


Inquire Device Bitmap 


Inquire Device Class 


_ Fortran Binding _ 

integer function cfqbtbltalign(base, width, px, py, 

1 maxpx, maxpy, name) 
integer base 
integer width 
integer px 
integer py 
integer maxpx 
integer maxpy 
integer name 

integer function cfqcellarr(name, px, qx, rx, py, qy, 

1 ry, dx, dy, colorind) 

integer name 

integer px, py 

integer qx, qy 

integer rx, ry 

integer dx, dy 

integer colorind(*} 

integer function cfqdevbtmp(name, map) 
integer name 
integer*4 map 

integer function cfqdevclass(output, input) 
integer output, input 


Table G-3 SunCGI Fortran Binding — Part III 


CGI Specification Name 


Inquire Device 
Identification 

Inquire Drawing Mode 


Inquire Event Queue 
State 


Fortran Binding 


integer function cfqdevid(name, devid) 
integer name 
character*(*) devid 

integer function cfqdrawmode(visibility, source, 

1 destination, combination) 

integer visibility 

integer source 

integer destination 

integer combination 

integer function cfqevque(qstate, qoflow) 
integer qstate 
integer qoflow 
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Table G-3 SunCGI Fortran Binding - Part III — Continued 


CGI Specification Name 
Inquire Fill Area 
Attributes 


Inquire Input 
Capabilities 


_ Fortran Binding _ 

integer function cfqflareaatts(style, vis, color, hindex, 

1 pindex, bindex, pstyle, pwidth, pcolor) 

integer style, vis, color 

integer hindex, pindex, bindex 

integer pstyle 

real pwidth 

integer pcolor 

integer function cfqinpcaps(valid, numloc, numval, numstrk, 

1 numchoice, numstr, numtrig, evqueue, asynch, coordmap, 

2 echo, tracking, prompt, acknowledgement, trigman) 
integer valid 

integer numloc 
integer numval 
integer numstrk 
integer numchoice 
integer numstr 
integer numtrig 
integer evqueue 
integer asynch 
integer coordmap 
integer echo 
integer tracking 
integer prompt 
integer acknowledgement 
integer trigman 
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Table G-3 SunCGI Fortran Binding - Part III — Continued 


CGI Specification Name 


Inquire LJD State List 


Inquire LID State 


Fortran Binding 


integer function cfqlidstatelis(devclass, devnum, valid, 

1 state, prompt, acknowledgement, x, y, xlist, ylist, n, 

2 val, choice, string, segid, pickid, n, triggers, 

3 echotype, echosta, echodat) 
integer devclass 
integer devnum 
integer valid 
integer state 
integer prompt 
integer acknowledgement 
integer x 
integer y 
integer xlist(*> 
integer ylist(*) 
integer n 
real val 
integer choice 
character*{*) string 
integer segid 
integer pickid 
integer n 

integer triggers(*) 
integer echotype 
integer echosta 
integer echodat 

integer function cfqlidstate(devclass, devnum, valid, 

1 state) 
integer devclass 
integer devnum 
integer valid 
integer state 
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Table G-3 

SunCGI Fortran Binding — Part III — Continued 

CGI Specification Name 

Fortran Binding 


Inquire UD Capabilities 


Inquire Line Attributes 


Inquire Marker 
Attributes 


Inquire Output 
Capabilities 

Inquire Output Function 
Set 


Inquire Pattern 
Attributes 


integer function cfqlidcaps(devclass, devnuin, valid, 

1 sample, change, nuinassoc, trigassoc, prompt, 

2 acknowledgement, echo, echotype, n, classdep, state) 
integer devclass 

integer devnum 
integer valid 
integer sample 
integer change ^ 

integer numassoc 
integer trigassoc(*) 
integer prompt 
integer acknowledgement 
integer echo(*) 
integer echotype(*) 
integer n 

character*(*) classdep 
integer state(*) 

integer function cfqlnatts(style, width, color, index) 
integer style 
real width 

integer color, index 

integer function cfqmkatts(type, size, color, index) 
integer type 
real size 

integer color, index 

integer function cfqoutcap(first, last, list) 
integer first, last 
character*80 list(*) 

integer function cfqoutfunset(level, support) 
integer level 
integer support 

integer function cfqpatatts(cindex, row, colximn, colorlis, 

1 X, y, dx, dy) 

integer cindex 

integer row 

integer column 

integer colorlis(*) 

integer x 

integer y 

integer dx 

integer dy 
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Inquire Physical integer function cfqphyscsys (name, xbase, ybase, xext, yext. 

Coordinate System 1 xunits, yunits) 

integer name 
integer xbase, ybase 
integer xext, yext 
real xunits, yunits 

Inquire Pixel Array integer function cf qpixarr (px, py, m, n, colorind, name) 

integer px, py 
integer m, n 
integer colorind(*) 
integer name 

Inquire Text Attributes integer function cfqtextatts (fontset, index, cfont, prec, 

1 efac, space, color, hgt, bx, by, ux, uy, path, halign, 

2 valign, hfac, cfac) 

integer fontset, index, cfont, prec 

real efac, space 

integer color, hgt 

real bx, by, ux, uy 

integer path, halign, valign 

real hfac, cfac ^ 

Inquire Text Extent integer function cfqtextext (string, nextchar, ^ 

1 conx, cony, llpx, llpy, ulpx, ulpy, urpx, urpy) 

character*(*) string 

character*(*) nextchar 

integer conx 

integer cony 

integer llpx 

integer llpy 

integer ulpx 

integer ulpy 

integer urpx 

integer urpy 
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Table G-3 

SunCGI Fortran Binding — Part III — Continued 

CGI Specification Name 

Fortran Binding 


Q 


O 


Inquire Trigger 
Capabilities 


Inquire Trigger State 


Inquire VDC Type 
Interior Style 

Line Color 

Line Endstyle 
(SunCGI Extension) 

Line Type 

Line Width Specification 
Mode 


integer function cfqtrigcaps(trigger, valid, change, n, 

1 class, assoc, niaxassoc, prompt, acknowledgement, 

2 name, description) 
integer trigger 
integer valid 
integer change 
integer n 

integer class(*) 
integer assoc(*) 
integer maxassoc 
integer prompt 
integer acknowledgement 
character*(*) name 
character*(*) description 

integer function cfqtrigstate(trigger, valid, state, n, 

1 class, assoc) 

integer trigger 

integer valid 

integer state 

integer n 

integer class(*) 

integer assoc(*) 

integer function cfqvdctype(type) 
integer type 

integer function efintstyle(istyle, perimvis) 
integer istyle 
integer perimvis 

integer function cflncolor(index) 
integer index 

integer function cflnendstyle(ttyp) 
integer ttyp 

integer function cflntype(ttyp) 
integer ttyp 

integer function cflnspecmode(mode) 
integer mode 



f#sun 

inicnMyitaf n 


Version C of 17 March 1986 






166 SuqCGI Reference Manual 


Table G-4 SunCGI Fortran Binding - Part IV 


CGI Specification Name 


Line Width 

Marker Color 

Marker Size 
Specification Mode 

Marker Size 

Marker Type 

Open CGI 
(SunCGI Extension) 

Open View Surface 
(SunCGI Extension) 


Partial Polygon 


Pattern Index 


Pattern Reference Point 


Pattern Size 


Pattern Table 


Forman Binding 


integer function cflnwidth(index) 
real index 

integer function cfmkcolor(index) 
integer index 

integer function cfmkspecmode(mode) 
integer mode 

integer function cfmksize(index) 
real index 

integer function cfmktype(ttyp) 
integer ttyp 

integer function cfopencgiO 

integer function cfopenvws(name, screenname, windowname, 

1 windowfd, retained, dd, cmapsize, cmapname, flags, 

2 ptr) 
integer name 

character*(*) screenname 
character*!*) windowname 
integer windowfd 
integer retained 
integer dd 
integer cmapsize 
character*!*) cmapname 
integer flags 
character*!*) ptr 

integer function cfppolygon(xcoors, ycoors, n, flag) 

integer xcoors(*) 

integer ycoors!*) 

integer n 

integer flag 

integer function cfpatix(index) 
integer index 

integer function cfpatrefpt(x, y) 
integer x, y 

integer function cfpatsize(dx, dy) 
integer dx, dy 

integer function cfpattable(index, m, n, colorind) 
integer index 
integer m, n 
integer colorind!*) 
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Table G-4 SunCGI Fortran Binding — Part IV — Continued 


CGI Specification Name 
Pattern with Fill Color 
(SunCGI Extension) 


_ Fortran Binding 

integer function cfpatfillcolor(flag) 
integer flag 


Perimeter Color 


integer function cfperimcolor(index) 
integer index 


Perimeter Type 


integer function cfperimtype(ttyp) 
integer ttyp 


Perimeter Width 
Specification Mode 

Perimeter Width 
Pixel Array 


Polygon 


Polyline Bundle Index 
Polyline 


Polymarker Bundle 
Index 

Polymarker 


Rectangle 

Release Input Device 


integer function cfperimspecmode(mode) 
integer mode 

integer function cfperimwidth(index) 
real index 

integer function cfpixarr(px, py, iti, n, colorind) 
integer px, py 
integer m, n 
integer colorind(*) 

integer function cfpolygon(xcoors, ycoors, n) 
integer xcoors(*) 
integer ycoors(*) 
integer n 

integer function cfpolylnbundix(index) 
integer index 

integer function cfpolyline(xcoors, ycoors, n) 
integer xcoors(*) 
integer ycoors(*) 
integer n 

integer function cfpolymlcbundix(index) 
integer index 

integer function cfpolymarker(xcoors, ycoors, n) 
integer xcoors(*> 
integer ycoors(*) 
integer n 

integer function cfrectangle(xbot, ybot, xtop, ytop) 
integer xbot, ybot, xtop, ytop 

integer function cfrelidev(devclass, devniam) 
integer devclass 
integer devnum 
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Table G-5 SunCGI Fortran Binding - Part V 


CGI Specification Name 


Fortran Binding 


Request Input integer function cfreqinp (devclass, devnum, timeout, 

1 valid, X, y, xlist, ylist, n, val, choice, string, 

2 segid, pickid, trigger) 
integer devclass 

integer devnum 
integer timeout 
integer valid 
integer x, y 
integer xlist(*) 
integer ylist(*) 
integer n 
real val 
integer choice 
character*(*) string 
integer segid 
integer pickid 
integer trigger 


Reset to Defaults 


integer function cfrsttodefs() 


Sample Input 


Selective Flush of Event 
Queue 


Set Aspect Source Flags 

Set Default Trigger 
Associations 


integer function cfsampinp(devclass, devnum, valid, x, y, 

1 xlist, ylist, n, val, choice, string, segid, pickid) 

integer devclass 

integer devnum 

integer valid 

integer x, y 

integer xlist(*) 

integer ylist{*) 

integer n 

real val 

integer choice 

character*(*) string 

integer segid 

integer pickid 


integer function cfsflusheventqu(devclass, devnum) 
integer devclass 
integer devnum 


integer function cfsaspsouflags(fval, fnum, n) 
integer fval(*), fnum(*), n 


integer function cfsdefatrigassoc(devclass, devnum) 
integer devclass 
integer devnum 
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Table G-5 SunCGI Fortran Binding - Part V — Continued 

CGI Specification Name 

Fortran Binding 

Set Drawing Mode 

integer function cfsdrawmode(visibility, source, 

1 destination, combination) 

integer visibility 
integer source 
integer destination 
integer combination 


Set Error Warning Mask 

integer function cfserrwarrtmk (action) 
integer action ^ 


Set Global Drawing 

Mode 

(SunCGI Extension) 

integer function cfsgldrawmode(combination) 
integer combination 


Set Initial Value 

integer function cfsinitval(devclass, devnum, x, 

1 xlist, ylist, n, val, choice, string, segid, 

integer devclass 

integer devnum 

integer x, y 

integer xlist(*) 

integer ylist(*) 

integer n 

real val 

integer choice 

character*(*) string 

integer segid 

integer pickid 

pickid) 

SetUpSIGWINCH 
(SunCGI Extension) 

integer function cfsupsig(name, sig_function) 
integer name 
external sig_function 


Set VALUATOR Range 

integer function ofsvalrange(devnum, mn, mx) 
integer devnum 
real mn, mx 


Text Alignment 

integer function cftextalign(halign, valign, hcalind, 

1 vcalind) 

integer halign 
integer valign 
real hcalind, vcalind 

Text Bundle Index 

integer function eftextbundix(index) 
integer index 


Text Color 

integer function cftextcolor(index) 
integer index 


Text Font Index 

integer function cftextfontix(index) 
integer index 
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Table G-5 SunCGI Fortran Binding — Part V — Continued 


CGI Specification Name 


Text Precision 


Track Off 


Track On 


VDC Extent 


VDM Text 


Fortran Binding 


integer function cftextprec(ttyp) 
integer ttyp 

integer function cftext(x, y, string) 
integer x 
integer y 

character*(*) string 

integer function cftrackoff(devclass, devnum, tracktype, 

1 action) 
integer devclass 
integer devn\3jn 
integer tracktype 
integer action 

integer function cftrackon(devclass, devnum, echotype, 

1 exlow, eylow, exup, eyup, x, y, xlist, ylist, n, val, 

2 choice, string, segid, pickid) 
integer devclass 

integer devnum 
integer echotype 
integer exlow 
integer eylow 
integer exup 
integer eyup 
integer x, y 
integer xlist(*) 
integer ylist(*) 
integer n 
real val 
integer choice 
character*(*) string 
integer segid 
integer pickid 

integer function cfvdcext(xbot, ybot, xtop, ytop) 
integer xbot, ybot, xtop, ytop 

integer function cfvdmtext(x, y, flag, string) 

integer x 

integer y 

integer flag 

character*{*) string 
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Short C Binding 


Short C Binding 



o 














H 


Short C Binding 


At the time SunCGI was implemented, there was no official ANSI C binding for 
CGI. Sun Microsystems has tried to anticipate the eventual C binding with a set 
of shorter function names. The SunCGI binding is inspired by the C language 
binding of GKS. These names are contained in the header file <cgicbinci. h> 
which must be included in an application program using the short C binding. 


Table H-1 Correspondence Between Long and Short C Names 


Long Name 

Short Name 

activate_vws 

Cactvws 

append_text 

Captext 

associate 

Cassoc 

await_event 

Cawaitev 

bitblt_pattern_array 

Cbtblpatarr 

bitbit_patterned._source_array 

CbtbIpat s ouarr 

bitblt_source_array 

Cbtblsouarr 

cell_array 

Ccellarr 

character_expansion_factor 

Ccharexpfac 

character_height 

Ccharheight 

character_orientation 

Ccharorientation 

character_path 

Ccharpath 

character_set_index 

Ccharsetix 

character_spacing 

Ccharspacing 

circle 

Ccircle 

circular___arc_3pt 

Ccircarcthree 

c ir cular_^ar c_^3pt_clo s e 

Ccircarcthreecl 

circular_arc_center 

Ccircarccent 

circular_arc_center_close 

Ccircarccentcl 

clear_control 

Cclrcont 

clear_^view__surface 

Cclrvws 

clip_indicator 

Cclipind 

clip_rectangle 

Ccliprect 

close_cgi 

Cclosecgi 

close_vws 

Cclosevws 

color_table 

Ccotable 

deactivate_vws 

Cdeactvws 
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Table H-1 Correspondence Between Long and Short C Names — Continued 

Long Name 

Short Name 

define_bundle index 

Cdefbundix 

device__viewport 

Cdewpt 

disable_event s 

Cdaevents 

dis joint_polyline 

Cdpolyline 

dissociate 

Cdissoc 

echo_off 

Cechooff 

echo_on 

Cechoon 

echo_update 

Cechoupd 

ellipse 

Cellipse 

elliptical_arc 

Celliparc 

elliptical_arc_close 

Celliparccl 

enable_e vents 

Cenevents 

fill_area_bundle_index 

Cflareabundix 

fill_color 

Cflcolor 

fixed_font 

Cfixedfont 

flush_event_queue 

Cflusheventqu 

get_last_requested_input 

Cgetlastreqinp 

hard_reset 

Chardrst 

hatch_index 

Chatchix 

initialize_lid 

Cinitlid 

initiate_request 

Cinitreq 

inquire_aspect_source_flags 

Cqasfs 

i nqu i r e__b i t b 1 t_a 1 ig nme n t s 

Cqbtblalign 

inquire_cell_array 

Cqcellarr 

inquire_device_bitmap 

Cqdevbtmp 

inquire_device__class 

Cqdevclass 

inquire_device_identification 

Cqdevid 

inquire_drawing_inode 

Cqdrawmode 

inquire_event_queue_state 

Cqevquestate 

inquire_f ill_area_attributes 

Cqflareaatts 

inquire_input_capabilities 

Cqinpcaps 

inquire_lid_capabilities 

Cqlidcaps 

inquire^lid_state 

Cqlidstate 

inquire_^lid_state_list 

Cqlidstatelis 

inquire_line_attributes 

Cqlnatts 

inquire_marker_attributes 

Ccpnkatts 

inquire_output_capabilities 

Cqoutcap 

inquire_output_function_s et 

Cqoutfunset 

inquire_pattern_attributes 

Cqpatatts 

i n quir e__phy s i ca l_c o or dina t e_s y s t em 

Cqpbyscsys 

inquire_pixel_array 

Cqpixarr 

inquire_text_attributes 

Cqtextatts 

inquire_text_extent 

Cqtextext 

inquire_trigger_capabilities 

Cqtrigcaps 

inquire___trigger_state 

Cqtrigstate 

inquire_vdc_type 

Cqvdctype 
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Table H-1 Correspondence Between Long and Short C Names — Continued 

Long Name 

Short Name 


interior_style 

Cintstyle 


line_color 

Clncolor 


line_endstyle 

Clnendstyle 


line_type 

Clntype 


line_width 

Clnwidth 


line_width_specification_mode 

Clnwidthspecmode 


marker_color 

Cmkcolor 


inarlcer_size “ 

Cmksize 


inarker_size_specification_mode 

Cmksizespecmode 


inarker_type 

Cmktype 


open_cgi 

Copencgi 


open_vws 

Copenvws 


partial__polygon 

Cppolygon 


pattern_index 

Cpatix 


pattern_reference_point 

Cpatrefpt 


pattern_size 

Cpatsize 


pattern_table 

Cpattable 


pattern_with_fill_color 

Cpatfillcoior 


periineter_color 

Cperimcolor 


perimeter_type 

Cperimtype 


perimeter_width 

Cperimwidth 


perimeter_width_specification_mode 

Cperimwidthspecmode 


pixel_array 

Cpixarr 


polygon 

Cpolygon 


polyline 

Cpolyline 


polyline_bundle_index 

Cpolylnbundix 


polymarker 

Cpolymarker 


polymarker_bTindle_Index 

Cpolymkbundix 


rectangle 

Crectangle 


release_input_device 

Crelidev 


request_input 

Creqinp 


reset_to_defaults 

Crsttodefs 


sample_input 

Csampinp 


selective__flush of event queue 

Cselectflusheventqu 


set_aspect_source_flags 

Csaspsouflags 


set_default_trigger_associations 

Csdefatrigassoc 


set___drawing_mode 

Csdrawmode 


s et_e r r o r_war ning_ma s k 

Cserrwarnmk 


set_global_drawing_mode 

Csgldrawmode 


set___initial^value 

Csinitval 


set_up_sigwinch 

Csupsig 


set_valuator_range 

Csvalrange 


text 

Ctext 


text_aligninent 

Ctextalign 


text_bundle_index 

Ctextbundix 


text_color 

Ctextcolor 
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Table H-1 Correspondence Between Long and Short C Names — Continued 


Long Name 


Short Name 


text_font_index 

Ctextfontix 

text_precision 

Ctextprec 

track_off 

Ctrackoff 

track_on 

Ctrackon 

vdc_extent 

Cvdcext 

vdm text 

Cvdmtext 
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Index 


Special Characters 
<cgicbind.h>, 173 
<cgiconstants.h>, 111 
<cgidefs.h>, 111 


bundled attributes, 54 thru 51 

def ine_bundle_ind©x, 56 
8et_aspect_source_f lags, 56 
bundles, 54 


A 


Activate View Surface (SunCGI Extension), 16, 154 
activate_vws, 16 
ANSI, XV 


Append Text, 43,154 
append_text, 43 
Associate, 85, 154 



associations, 27 
adding, 86 
removing, 87 

asynchronous input functions, 92 thru 93 
attribute inquiries 

inquire_a3pect_source_flags, 78 
inquixe_fill_area_attributes, 76 
inquire_line_at.tributes, 75 
inquire_marker_attributaa, 75 
inquire_patt.ern_attributes, 76 
inc[uire_text_attributes, 77 
attribute inquiry functions, 75 thru 78 
attributes, 53 thru 78 
bundled, 54 thru 57 
color, 74 thru 75 
fill area, 62 thru 63 
line, 57 thru 60 
pattern, 63 thru 66 
perimeter, 66,68 
polymarker, ^ thru 61 
solid object, 61 thru 68 
text, 68 thru 74 
Await Event, 95 ,154 
await event, 95 


B 


bitblt,33,42,49 



Bitfflt Pattern Array, 46,154 
BitBU Patterned Source Array, 46,154 
BitBlt Source Array, 45 ,154 
bitblt_pattern_array, 46 
bitblt_pattcmed_3 0 urce_array, 46 
bitblt_ 80 urce_array, 45 
bundle table, 54 


c 

Cell Array, 44,154 
cell_array, 44 
cfactvws, 154 
cfaptext, 154 
cf assoc, 154 
cfawaitev, 154 
cfbtblpatarr, 154 
cfbtblpatsouarr, 154 
cfbtblsouarr, 154 
cfcellarr, 154 
cfcharexpfac, 154 
cfcharheight, 154 
cfcharorient, 154 
cfchaxpath, 154 
cfcharsetix, 154 
cf chat spacing, 154 
cfcircarccent, 154 
cfclrcarccentcl, 154 
cfcircarcthree, 154 
cfcircarcthreecl, 154 
cfcitcle, 154 
cfclipind, 154 
cf cliprect, 154 
cfclosecgi, 154 
cfclosevws, 154 
cfclxcont, 154 
cfclrvws, 154 
cfcotable, 157 
cfdaevents, 157 
cfdeactvws, 157 
cf defbundlx, 157 
cfdewpt, 157 
cfdissoc, 157 
cfdpolyline, 157 
cfelliparc, 157 
cfelliparccl, 157 
cfellipse, 157 
cfenevents, 157 
cffixedfont, 157 
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cf flareabundix, 157 
cf flcolor, 157 
cf flusheventqu, 157 
cfgetlastreqinp, 157 
cfhardrst, 157 
cfhatchix, 157 
cfinitlid, 157 
cf initreq, 157 
cfintstyie, 160 
cflncolor, 160 
cf Inendstyle, 160 
cf Inspecmoda, 160 
cflntype, 160 
cf Inwidth, 166 
cfmkcolor, 166 
cfmksize, 166 
cfmkspecmode, 166 
cfmJctype, 166 
cf opencgi, 166 
cf openvws, 166 
cfpatfillcolor, 166 
cfpatix, 166 
cfpatrefpt, 166 
cfpatsize, 166 
cfpat.t.abla, 166 
cfperimcolor, 166 
c£peri.mspecinode, 166 
cfporimtype, 166 
cfperimwidth, 166 
cfpixazr, 166 
cfpolygon, 166 
cfpolyline, 166 
cfpolylnbundix, 166 
cfpolymarker, 166 
cfpolymkbundix, 166 
cfppolygon, 166 
cfqasf 3,157 
cf qbtbltalign, 157 
cfqcellarr, 157 
cf qdevbtnp, 157 
cfqdevclass, 157 
cfqdevid, 160 
cfqdravrmode, 160 
cf qevque, 160 
cfqf lareaatts, 160 
cfqlnpcaps, 160 
cf qlidcapSt 160 
cfqlidstate, 160 
cf qli-dstabells, 160 
cfqlnabts, 160 
cfqmkatts, 160 
cfqoutcap, 160 
cfqoutfunset, 160 
cfqpatatta, 160 
cfqphyscsys, 160 
cf qpixarr, 160 
cfqtextatts, 160 
cfqtextext, 160 


cfqtrigcaps, 160 
cfqtrigstate, 160 
cfqvdctype, 160 
cfrectangle, 166 
cfrelidev, 166 
cf reqinp, 168 
cfrsttodef 3,168 
cfsan^inp, 168 
cfaaspsouflags, 168 
cfsdefatrigassoc, 168 
cfsdrawmode, 168 
cfserrwarnntk, 168 
cfaflushevenbqu, 168 
cf sgldzawrnode, 168 
cfsinltval, 168 
efsupsig, 168 
cfsvalrange, 168 
cfbext:, 168 
cftextalign, 168 
cftexbbundix, 168 
cftaxPcolor, 168 
cfbexbfontlx, 168 
cftextprec, 168 
cftrackoff, 168 
cfbrackon, 168 
cfvdcext, 168 
cfvdmtexb, 168 

CGI, 3 

audience, xv 
controUi^ document, xv 
CGI Tool, 14 

CGI type definitions, 111 thm 120 
CGI with Pixwins, 143 thru 148 
CGI with pixwins 
example, 147 
functions, 145 thru 147 
using cgipw, 144 thru 145 
cg^w functions 

clo3e_cgi_pw, 144 
close_pw_cgi, 144 
open__cgi_pw, 143 
opon_pw_cgi, 143 
Character Expansion Factor, 70,154 
Character Height, 70,154 
Character Orientation, 71,154 
Character Path, 72,154 
Character Set Index, 69,154 
Character Spacing, 70,154 
char8ebttr_axpansion_£actor, 70 
character^helght, 70 
charactez_OEientation, 71 
eharaetftE_path, 72 
characteE_8et_index, 69 
charaetar^^^spaeing, 70 
Circle, 38, IM- 
circle 

area of a, 38 
perimeter definition, 38 
circle, 38 
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Circular Arc 3pt, 40, 154 
Circular Arc 3pt Close, 41,154 
Circular Arc Center, 38,154 
Circular Arc Center Close, 39,154 
circular arcs 
center, 39 
close, 39 

direction of drawing, 39 
three-point, 40 
circular_arc_3pt, 40 
circular_arc_3pt_cloae, 41 
circular_arc_center, 38 
circular_arc_center_close, 39 
Clear Control, 21,154 
Clear View Surface, 21,154 
clear_control, 21 
clear_view_surface, 21 
Clip Indicator, 19, 154 
Clip Rectangle, 20,154 
clip_indicator, 19 
clip_rectangle, 20 
clipping, 17,19 
Close a CGI Pixwin, 144 
Close CGI (SunCGI Extension), 16, 154 
Close Pixwin CGI, 144 

Close View Surface (Surd3GI Extension), 16, 154 
clo8e_cgi, 16 
close_cgi_pw, 144 
close_pw_cgi, 144 
close_vws, 16 
color attributes, 74 thru 75 
color_table, 74 
coIortoble,59,74, 157 
color_table, 74 
conical output primitives, 33,34 thru 42 
control errors, 124 

coordinate definition errors, 124 thru 125 
current position, 103 


E 

ElUpse,41 ,157 
Ell^tiad Arc, 41 ,157 
Elliptical Arc Close, 42,157 
elliptical arcs, 41 
drawing of, 42 
elliptical_arc, 41 
elliptical_arc_clo8ei 42 
Enable Events, 95,157 
enable^events, 95 
error, 21 

control, 21 
errors 

control, 124 

coordinate definition, 124 thru 125 
uzqjlementation dependent, 131 
input, 129 thru 130 
ou^ut attribute, 125 thru 127 
output primitive, 121 thru 129 
possible causes of visual, 131 thru 133 
state, 123 thru 124 
event queue, 87,96 
status, 98 

event queue input functions, 93 thru 98 

F 

fill area attributes, 62 thru 63 
Fill Area Bundle Index, 62,157 
FiU Color, 63,157 
f ill_area_bundle_indGx, 62 
f ill_color, 63 

Fixed Font (SunCGI Extension), 71,157 
f ixed_font,71 
Flush Event Queue, 96,157 
f lu8h_event_queue, 96 
FORTRAN interface 

function definitions, 154 thru 170 
Prograimning Hints, 151 thru 152 
using FORTRAN, 151 


D 

data type definitions. 111 thru 120 

Deactivate View Surface (SunCGI Extension), 16,157 

doactivate_vw3, 16 

Define Bundle Index (SunCGI Extension), 56, 157 

def ine_bundle_index, 56 

device coordinates (see screen space), 17 

Device Viewport, 19,157 

devic«_viewport, 19 

Disable Events, 98,157 

di8able_«vor\ts, 98 

Disjoint Polyline, 34,157 

dis joint_polyline, 34 

Dissociate, 86,157 

documentation conventions, xv 

drawing mode, 6,42 

drawing modes, 48 xAnt 50 
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G 

geometrical output primitives, 33,33 thru 42 
Get Last Requested Input, 97,157 
got_laat_requ«sted_input, 97 
global polygon list, 35,36 

H 

Hard Reset, 20,157 
hard^reset, 20 
batch, 63 

Hatch Index, 64, \S1 
hatch_lxrdex, 64 

I 

ICJSTROKE, 86 

inq>lementatioD dependent errors, 131 
include files, 4 
/«riaCze£JD,84,157 
initialize_lid, 84 
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initializing 

activate_vws, 16 
close_cgi, 16 
close_vws, 16 
deactivate_vws, 16 
open_cgi, 12 
open_vws, 13 
initializing SunCGI, 12 
Initiate Request, 92 ,157 
init.iate_requeat, 92 
input device, 84 
c^abilities, 27 
status, 98 

input device initialization functions, 84 thru 90 
input devices 

initialization, 84 
input eirors, 129 130 

input functions 

associate, 85 
await_event, 95 
disable_events, 98 
dissociate, 86 
enable_eventa, 95 
flush_event_queue, 96 
gGt_last_requested_input, 97 
initiali 2 e_lid, 84 
initiate_request, 92 
inquire_evGnt_q;ueue_state, 99 
inquire_lid_state, 99 
inquire_lid_state_list, 98 
inquire_trigger_state:, 99 
releasG_input_device, 85 
reqpiG3t_input, 91 
8ainple_input, 97 

selective_flU3h_of_event_queue, 96 
8et_default_trigger_associations, 86 
8et_initial_valuG, 87 
Bet_valuator_range, 87 
track_off, 89 
track_on, 88 

Inquire Aspect Source Flags, 78,157 
Inquire BitBlt Alignments, 48,157 
Inquire Cell Array, 47,157 
Inquire Device Bitmap, 157 

Irujuire Device Class, 25, 157 
Inquire Device Identification, 25,160 
Inquire Drawing Mode, 50, 160 
Inquire Event Queue State, 99,160 
Inqiure Fill Area Attributes, 76,160 
Inquire Input Capabilities, 27,160 
Inquire LID Capabilities, 28, 160 
Inquire UD State, 99,160 
Inquire UD State List, 98,160 
Inquire Line Attributes, 75,160 
Inquire Marker Attributes,lS, 160 
Inquire Output Capabilities, 27,160 
Inquire Output Function Set, 26,160 
Inquire Pattern Attributes, 76, 160 
Inquire Physical Coordinate System, 25, 160 
Inquire Pixel Array, 47,160 
InquireText Attributes,!!, 160 


Inquire Text Extent, 43,160 
InquireTrigger Capabilities, 29,160 
Inquire Trigger State, 99,160 
Inquire VDC Type, 26,160 
inqpiire_ 

a8pect__source_f lags, 78 
bitblt_alignment3,48 
CGll_array, 47 
dovice_bitniap, 48 
device_^class, 25 
device_identification, 25 
drawing_mode, 50 
ovent_queue_atate, 99 
f ill_area__attributes, 76 
input^^capabilities, 27 
lid_capabilities, 28 
lid__8tate_ii8t, 98,99 
line_at tributes, 75 
marker_attributes, 75 
output_capabilities, 27 
output_function_sGt, 26 
pattem_attribute3,76 
physical_coordinate_systen\ 25 
pixel__array, 47 
toxt_attribute3,77 
text_extent, 43 
* triggGr__cap 2 d>ilities, 29 
trigger_8tate, 99 
vdc_type, 26 
inquiiy Actions 

attributes, 75 thru 78 
interface negotiation, 24 thru 30 

inquire__device_clas3,25 
inquire_device_idontification, 25 
inquire_input_capabilities, 27 
inciuire_lid_capabilities, 28 
inquire_output_capabilities, 27 
inquire_output_function_set, 26 
inqpiiro_physical_eoordinate_3ystef!\ 25 
inquire_trigger_capabilities, 29 
inquire_vdc_typG, 26 
Interior Style, 62,160 
interior_8tyle, 62 
Uottopy, 17 

L 

line attributes, 57 thru 60 
line^color, 59 
line_«nd5tyle, 58 
line_^type, 58 
line_width, 59 

line_width_8pecification_mode, 59 
polylin«_bundle_index, 57 
Um Color, 59,160 

Line Endstyle (SunCGI Extension}, 58,160 

Line Type, 58,160 

Lam WUtth,59,166 

Line Width Specification Mode, 59,160 

line_color, 59 

line__end8tyle, 58 

line^type, 58 

line_width, 59 
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0 1ine_width_specif ioation_mode^ 59 
linking SunCGI, 3 
lint library, 5 
logical input device, 6 

M 

Marker Color, 61,166 

Marker Size, 61,166 

Marker Size Specification Mode, 60,166 

Marker Type, 60,166 

marker_color, 61 

marker_aize, 61 

marker_8ize_3pecification_mode, 60 
marker_type, 60 
measore, 6 


N 

negotiation functions, 5 
non-ietained windows, 14 
NORMAL VWSORF, 13, 15 




o 

open a CGI Pixwin, 143 

Open CGI (SunCGI Extension), 12, 166 

Open Pixwin CGI, 143 

Open View Surface (SunCGI Extension), 13,166 

open_cgi, 12 

open_cgi_pw, 143 

open_pw_cgi, 143 

open_vws, 13 

option sets, 3 

output attribute errors, 125 thru 127 
output primitive errors, 127 thru 129 
output primitives. 3,6,33 thru 50,104 
append_text, 43 
bitblt__pattern_array, 46 
bit bl t_pat 16rned_sou r ce_a rray, 
bitblt_source_array, 45 
cell_array, 44 
circle, 38 

circular_arc_3pt, 40 
c i r cu la r_ar c_3pt_c 1 o a e, 41 
circular_arc_center, 38 
circular_arc_center_close, 39 
conical, 33,34 thru 42 
dis joint__polyline, 34 
drawing modes, 48 thru 50 
ellipse, 41 
elliptical_arc,41 
elliptical_arc_clo3e, 42 
geometrical, 33 thru 42 
inquire_bitblt_alignments, 48 
inquize_cell_array, 47 
irtqtiir«_d«vice_bittTiap, 48 
inquire_drawing_niode, 50 
inquiro_pixel_array, 47 
inquire_text_extent, 43 
partial_polygon, 36 
pixel_array, 44 
polygorr, 35 


46 


ouQ>ut primitives, continued 
polygonal, 33,33 thru 38 
polyline, 34 
polymarker, 35 
raster, 42/Aru 48 
rectangle, 38 
80 t_drawing_mode, 49 
set_jglobal_drawing_mode, 50 
text, 42 
vdm_text, 43 

P 

Partial Polygon, 36, 166 
perrtial_polygon, 36 
paaan,63 

reference point, 65 
pattern attributes, 63 tAnt 66 
hatch_index, 64 
pattem_index, 65 
pattem_ref erence_point, 65 
pattem_size, 66 
pattem_t^d3le, 65 
pattom_with_fill_color, 66 
Pattern Index, 65,166 
Pattern R^erence Point, 65, 166 
Pattern Size, 66, 166 
Pattern Table, 65,166 

Pattern with Fill Color (SunCGI Extension), 66,166 

pattem_index, 65 

pattem_ref erencejpoint, 65 

pattem_aize, 66 

pattem_table, 65 

patteni_with_fill_color 

pattem_with_f ill_color, 66 
peruneter 

endstyle, 67 

perimeter attributes, 66 thru 68 
perinieter_color, 68 
perimeter_type, 66 
perimeter_width, 67 

periineter_width_specification_mode, 67 
Peruneter Color, 68,166 
Perimeter Type, 66,166 
p^imeter visibili^, 62 
Perimeter Width, 67,166 
Perimeter Width Spec^ication Mode, 67,166 
p«rlmeter_color, 68 
p«rinMter_type, 66 
perimeter^jwidth, 67 

perimet er_width_8peci £i cati on_^mod^ 67 
pie chart, 39 
Pixel Array, 44,166 
plxel_array, 44,45 
Pixwms with CGI, 143 thru 148 
pixwins with CGI 
example, 147 
functioiis, 145 thru 147 
using cgipw, 144 thru 145 
point 

drawing a, 38 
Polygon, 35,166 
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polygon 

with undrawn edge(s}, 36 
polygonal primitives, 33,33 thru 38 
Polyline, 34,166 
Polyline Bundle Index, 57,166 
polyline_bundlG_index, 57 
Polymarker, 35,166 
polymarker attributes, 60 thru 61 
marker_eolor, 61 
inarker_size, 61 

marker_size_spGcification_mode, 60 
marker_type, 60 
polyinarker_bundle_index, 60 
Polymarker Bundle Index, 60,166 
polyxnarker_bundle_ind6x, 60 

R 

raster primitives, 33,42 thru 48 
Rectangle, 38,166 
Release Input Device, 85,166 
release__input_device, 85 
Request Input, 91,168 
request register, 92,97 
request;_input, 91 
Reset to Defaults, 20, 168 
re8et_to_def aults, 20 
retained windows, 14 

s 

Sample Input, 97,168 
sairplG_input, 97 
screen space, 5,17 
definition, 19 

Selective Flush of Event Queue, 96,168 

selectiVG_f lush_of_event_q:ueue, 96 

Set Aspect Source Flags, 56,168 

Set Default Trigger Associations, 86, 168 

Set Drawing Mode, 49,168 

Set Error yfarrung Mask, 22,168 

Set Globed Dretwing Mode (SunCGI Extension), 50,168 

Set Initied Value, 87,168 

Set Up SIGWINCH (SunCGI Extension), 23, 168 

Set VALUATOR Range, 87.168 

8ot_aspect^source_f lags, 56 

8et_default_trigger_a»sociations, 86 

set:_drawing_tnode, 49 

8et_error_waniing_inask, 22 

set_global_drawing_mode, 50 

8et__initial_value, 87 

s«t_up_8igwinch, 23 

8Gt_valuator_range, 87 

Short C Binding, 4,173 

SIGWINCH, 6,22 

solid object attributes, 61 thru 68 

£ill__area_bmidle_index, 62 
f ill_color, 63 
interior_st;ylG, 62 
specified device, 28 
state errors, 123 thru 124 


status inquiries, 98 thru 100 
Sun Workstation, 25 
SunCGI, 3 

with SunCGI, 22 thru 24 
SonView 

8ot_up_8igwinch, 23 
using SunCGI with, 22,24 
fjnichtonous input functions, 90 thru 92 

T 

Text, 42,168 

Teta AUgnment, 72,168 

text attributes, 68 dau 74 

charactar__expansion_f actor, 70 
character_height, 70 
characber_orlentatlon, 71 
character_path, 72 
character_8et__index, 69 
character_8pacing, 70 
f ixed_f ont, 71 
text_alignment, 72 
text_bundle_index, 68 
text_color, 71 
text_f ont__index, 69 
text_precision, 68 
Text Bundle Index, 68,168 * 

Text Color, 11,16% 

Text Font Index, 69,168 
Text Precisietn, 68,168 
text precision 

detailed definition, 68 
text, 42 

appended, 43 
text__aligninent, 72 
text, 42 

text_bundle_index, 68 
text^color, 71 
text_font_index, 69 
text__proci8ion, 68 
textured line, 58 
timeout, 83 
track, 88 

Track Off, 89,168 
TrackOn, 88,168 
trnck_off, 89 
track__on, 88 
tracking, 88 thru 90 
trigger, 6,27,86 
Trigger 

Cq>abilities, 29 
trigger 

intoaction with STROKE device, 86 
status, 98 

type definitions. 111 thru 120 

u 

unsupported CGI functions, 107 thru 108 
using SunCGI, 3 
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C\ ^ 

'^^DC Extent, 17,168 
VDC space, 5, 17 
vdc_extent, 17 
VDI,xv 

VDMText,A3 ,168 
vdm_text, 43 
view surface, 11 
clear control, 21 
clearing, 20 
default states, 15 
view surface control, 17 thru 22 
clear^control, 21 
clear_view_surf ace, 21 
clip_lndical:or, 19 
cl ip_rect angle, 20 
device__viewport, 19 
hard_reset, 20 
reset_to_defaults, 20 
set_error_warning_mas)c, 22 
vdo_extent, 17 
view surfaces, 15 
active, 5 
initializing, 13 
multiple, 5,13 
visual errors 

possible causes, 131 thru 133 

w 

Q windows 

nonretained, 14 
retained, 14 

world coordinates (see vdc space), 17 
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